# Introduction

I apologize for how limited this documentation is, but as this extension is primarily a simple wrapper around SFML's C++ classes, I will rely on SFML's documentation to explain more detail about the classes and methods. This documentation is simply meant to explain which classes and methods are available in Ruby, as well as what changes have been made during the translation from C++ to Ruby.

As Ruby doesn't support native threading and has its own networking classes, I only exposed certain classes in the system, window, graphics, and audio libraries. For most exposed classes, the only changes I made were to make the methods start with a lower-case letter. For classes with simple Get/Set methods, I often drop the Get and Set to allow you to use sprite.left and sprite.left=. I also added a few to_i, to_f, and to_s methods where it seemed appropriate. Last but not least, I added an each iterator to VideoMode.

In addition to the C++ classes I exposed, I also added two helper classes in RubySFML.rb, one for rendering tiled sprites, and the other for dealing with sprites that use 2D velocity/accelerate calculations (TSprite and VSprite respectively).

### Tips for Windows Users

For the Windows users out there, I apologize for not being compatible with the one-click installer, but it's being built with Visual Studio 6.0, which is ridiculously old and not compatible with any of the SFML libraries. There's a free version of Visual Studio 2005 available, and the Ruby source compiles very smoothly with it, so I can't think of a good excuse for the one-click installer to still be using 6.0.

On the bright side, you can distribute your game in a self-sufficient package by zipping it up with the bin and lib folders that come with the Windows binary version of this extension. Add a simple installer that creates a program group icon that runs "%install_path%\bin\ruby.exe %install_path%\my_game.rb", and you're all set. Oh yeah, OpenAL needs to be installed on any machine running this. Fortunately it is a very small/simple install, and it should be easy for you to either bundle it with your distribution or provide a link for your users to download it. All of this keeps your users from having to download/run the one-click installer, install all the necessary extensions, worry about compatibility issues, etc. It is likely that very few Windows users will ever play your game if you don't provide them everything they need to run it, so it's probably better this way.

Note: This custom build of Ruby does have gems and zlib (which is required by gems), but no other extensions are installed. Feel free to install any other gems/extensions you need (native mswin32 gems compiled with Visual Studio 6.0 may not work). Keep in mind that many gems often have large doc, examples, and test folders. Deleting these unnecessary folders, along with the gem cache folder, can significantly shrink the size of the file you're distributing.

### RubySFML Sample Code

    # Include the RubySFML extension
    require "RubySFML"
    include SFML

    # Create the main window
    mode = VideoMode.new 800, 600, 32
    window = RenderWindow.new mode, "RubySFML Test", false

    # Load a sprite to display
    image = Image.new "cute_image.jpg"
    sprite = Sprite.new image

    # Create a graphical string to display
    text = Text.new "Hello SFML", "arial.ttf", 50

    # Load a music and start playing it
    music = Music.new "nice_music.ogg"
    music.play

    # Start the game loop
    running = true
    while running
    	while event = window.getEvent
    		running = false if event.type == Event::Close
    	end

    	# Draw the sprite, then the text, and update the window
    	window.draw sprite
    	window.draw text
    	window.display
    end

### RubySFML Modules

- SFML - Contains all SFML classes, modules, and global methods.
- SFML::Event - Contains constants for all of the SFML enumerated event types.
- SFML::Key - Contains constants for all of the SFML enumerated key codes.
- SFML::Mouse - Contains constants for all of the SFML enumerated mouse button codes.

### RubySFML Classes

- SFML::Clock - A system clock using high-performance timers where available
- SFML::Color - A simple RGBA color class
- SFML::Drawable - A pure virtual class representing 2D objects to use with RenderWindow
- SFML::Event - A class representing various system events (like keyboard and mouse events)
- SFML::FloatRect - A simple rectangle made of 4 floats
- SFML::Image - A class for managing image files and textures
- SFML::Input - A class for checking the current state of various input devices
- SFML::IntRect - A simple rectangle made of 4 ints
- SFML::Music - A class for playing streaming music files
- SFML::PostFX - A class for mananging post-rendering shaders
- SFML::RenderWindow - A sub-class of Window which makes it easy to draw 2D sprites and text
- SFML::Sound - A class for playing sound clips
- SFML::SoundBuffer - A class for managing sound clips and sound files
- SFML::SoundBufferRecorder - A class for recording sound from a capture device, like a microphone
- SFML::Sprite - A class for managing/drawing 2D sprites
- SFML::Text - A class for managing/drawing 2D text (using ttf fonts)
- SFML::VideoMode - A class for managing video modes and window sizes
- SFML::View - A class for managing the 2D camera in RenderWindow
- SFML::Window - A class for creating/managing a suitable window for custom OpenGL rendering (also handles all input and events)

### RubySFML Methods (by module/class)

#### SFML

- checkExtension(str) - Returns true if the specifed OpenGL extension is supported.
- getMaxTextureSize - Returns the max texture size for the current display hardware.
- getMaxTextureUnits - Returns the max number of texture units for the current display hardware.

#### SFML::Clock

- initialize() - Default constructor
- to_s - Returns a formatted string representing this object (for debugging purposes)
- reset - Resets the clock
- elapsedTime,to_f - Returns the elapsed time since the last reset

#### SFML::Color

- initialize() - Default constructor
- initialize(n) - Builds the color from a 32-bit unsigned RGBA value (0x12345678 is r=0x78, g=0x56, b=0x34, a=0x12)
- initialize(r, g, b, a=255) - Builds the color from its separate components
- to_s - Returns a formatted string representing this object (for debugging purposes)
- r, g, b, a - Returns the r, g, b, and a values (respectively)
- r=, g=, b=, a= - Sets the r, g, b, and a values (respectively)
- toRGBA - Returns the 4 components as a 32-bit unsigned value (0x12345678 is r=0x78, g=0x56, b=0x34, a=0x12)
- to_i - Alias for toRGBA

#### SFML::Drawable

- initialize(left=0, top=0, scale=1, rotation=0, color=Color.White) - Initializes various members (scale can be a number or an array of two numbers)
- to_s - Returns a formatted string representing this object (for debugging purposes)
- left, left= - Gets/sets the left x position
- top, top= - Gets/sets the top y position
- scale, scale= - Gets/sets the scale of this object (get returns an array, set takes a num or an array
- color, color= - Gets/sets the base color of this object
- rotation, rotation= - Gets/sets the angle of rotation (in degrees)
- upVector - Gets this object's up vector (based on its angle of rotation)
- rightVector - Gets this object's right vector (based on its angle of rotation)
- setRotationCenter(x, y) - Sets the center of rotation for this object
- move(x, y) - Adds an offset to the left and top members
- rotate(a) - Adds an offset to the rotation member
- render(window) - (virtual) Override to add custom rendering code

#### SFML::Event

##### For all event types

- initialize - Takes no parameters
- to_s - Returns a formatted string representing this object (for debugging purposes)
- type - Returns the event type

##### For the Event::TextEntered event type

- char - Returns the character typed (only for Event::TextEntered events)

##### For Event::KeyPressed and Event::KeyReleased event types

- code - Returns the character code (only for Event::KeyPressed and Event::KeyReleased events)
- alt - Returns true if an Alt key is down (only for Event::KeyPressed and Event::KeyReleased events)
- control - Returns true if a Ctrl key is down (only for Event::KeyPressed and Event::KeyReleased events)
- shift - Returns true if a Shift key is down (only for Event::KeyPressed and Event::KeyReleased events)

##### For mouse and joystick event types

- delta - Returns the scroll wheel offset (only for Event::MouseWheelMoved events)
- buttons - Returns the state of the mouse buttons (only for mouse events)
- button - Returns the state of the joystick buttons (only for joystick events)
- x - Returns the x position (for mouse and joystick events)
- y - Returns the y position (for mouse and joystick events)
- z - Returns the z position (for joystick events)

##### For the Event::Resize event type

- width - Returns the new window width (only for Event::Resize events)
- height - Returns the new window height (only for Event::Resize events)

#### SFML::FloatRect

- initialize() - Default constructor
- initialize(left, top, right, bottom) - Initialize the rectangle's members
- to_s - Returns a formatted string representing this object (for debugging purposes)
- left, l - Gets the left x position
- left=, l= - Sets the left x position
- top, t - Gets the top y position
- top=, t= - Sets the top y position
- right, r - Gets the right x position
- right=, r= - Sets the right x position
- bottom, b - Gets the bottom y position
- bottom=, b= - Sets the bottom y position
- width, w - Gets the rectangle width
- height, h - Gets the rectangle height
- contains(x, y) - Returns true if the x, y position is inside the rectangle
- intersects(rect) - Returns the intersection of two rectangles (nil if there is no intersection)

#### SFML::Image

- initialize - Creates an empty image
- initialize(image) - Creates a copy of an image
- initialize(path) - Loads an image file using the specified path (raises a RuntimeError on failure)
- initialize(w, h, c=Color.Black) - Creates a blank image using the specified width, height, and color
- to_s - Returns a formatted string representing this object (for debugging purposes)
- getValidTextureSize(s) - (static) Returns the valid nearest texture size >= s
- width, w - Gets the image width
- height, h - Gets the image height
- smooth=, setSmooth(bool) - Sets the OpenGL texture parameter to linear interpolation for true or nearest for false
- repeat=, setRepeat(bool) - Sets the OpenGL texture parameter to repeat for true or clip for false
- loadFromFile(path) - Loads a file image using the specified path
- saveToFile(path) - Saves the image to a file using the specified path
- create(w, h, c=Color.Black) - Creates an empty image with the specified width, height, and color
- createMaskFromColor(color, a=0) - Scans the image for pixels of the specified color, and sets the alpha value of those pixels to a.
- resize(w, h, c=Color.Black) - Resizes the image. If the image grows, sets new pixels to the specified color.
- getPixel(x, y), [x,y] - Returns the color of the specified pixel.
- setPixel(x, y, c), [x,y]= - Sets the color of the specified pixel to c.
- update - Updates the image in video memory (call after manually setting pixels).
- bind - Bind the image for rendering (call if you're using this image with raw OpenGL calls).
- getTexCoords(rect) - Converts an IntRect representing pixel positions to a FloatRect representing texture coordinates.

#### SFML::Input

- initialize - Default constructor
- isKeyDown(key) - Returns true if the specified key is down
- isMouseButtonDown(button) - Returns true if the specified mouse button is down
- isJoystickButtonDown(n, button) - Returns true if the specified button on joystick n is down
- getMouseX - Returns the current x position of the mouse
- getMouseY - Returns the current y position of the mouse
- getJoystickX(n) - Returns the current x position of joystick n
- getJoystickY(n) - Returns the current y position of joystick n
- getJoystickZ(n) - Returns the current z position of joystick n

#### SFML::IntRect

- initialize() - Default constructor
- initialize(left, top, right, bottom) - Initialize the rectangle's members
- to_s - Returns a formatted string representing this object (for debugging purposes)
- left, l - Gets the left x position
- left=, l= - Sets the left x position
- top, t - Gets the top y position
- top=, t= - Sets the top y position
- right, r - Gets the right x position
- right=, r= - Sets the right x position
- bottom, b - Gets the bottom y position
- bottom=, b= - Sets the bottom y position
- width, w - Gets the rectangle width
- height, h - Gets the rectangle height
- contains(x, y) - Returns true if the x, y position is inside the rectangle
- intersects(rect) - Returns the intersection of two rectangles (nil if there is no intersection)

#### SFML::Music

- initialize(bufSize=44100) - Allows you to specify the buffer size.
- initialize(path) - Opens a music file using the specified path (raises a RuntimeError on failure).
- to_s - Returns a formatted string representing this object (for debugging purposes)
- loop, loop= - Gets/sets a boolean indicating whether the music should loop back to the beginning when it's finished playing.
- duration - Gets the duration of the sound stream.
- channels - Gets the number of channels in the sound stream (1=mono, 2=stereo).
- sampleRate - Gets the sample rate of the sound stream (44100 = CD quality).
- status - Gets the status of the music object (Sound::Stopped, Sound::Paused, Sound::Playing).
- open(path) - Opens a music file using the specified path (returns false on failure).
- play - Start the music.
- stop - Stop the music.

#### SFML::PostFX

- (Inherits all methods from SFML::Drawable)
- initialize() - Default constructor
- initialize(path) - Loads an effect file using the specified path.
- initialize(postFX) - Makes a copy of a PostFX object.
- loadFromFile(path) - Loads an effect file using the specified path (returns false on failure).
- setParameter(name, x, y=nil, z=nil, w=nil) - Sets the named parameter to an array of 1, 2, 3, or 4 floats.
- setTexture(name, image) - Sets a named texture parameter.

#### SFML::RenderWindow

- initialize(mode, title, style=Window::Resizable, antialias=0) - Creates a 2D render window using the specified VideoMode, title, and style
- to_s - Returns a formatted string representing this object (for debugging purposes)
- width, w - Gets the width of the window
- height, h - Gets the height of the window
- input - Gets the SFML::Input object for this window
- frameTime - Gets the amount of time it took to render the previous frame
- stencilBits - Gets the number of bits used in the stencil buffer
- depthBits - Gets the number of bits used in the back buffer
- view, view= - Gets/sets the SFML::View into the 2D world (2D camera position)
- backgroundColor= - Sets the background color for the whole window
- getEvent - Returns the next event in the window's event queue (or nil if the queue is empty)
- useVerticalSync(bool) - Use to enable/disable vsync
- showMouseCursor(bool) - Use to show/hide the operating system's mouse cursor
- display - Call to swap the front and back buffers to display the frame
- beginOpenGL - Call to save the OpenGL state before you call raw OpenGL methods
- endOpenGL - Call to restore the OpenGL state after you call raw OpenGL methods
- capture - Take a screenshot and return it as an image
- draw(obj) - Call to draw any object derived from SFML::Drawable
- setFramerateLimit - Set a fixed framerate (use 0 to disable it)

#### SFML::Sound

- initialize(sound) - Creates a copy of a Sound object
- initialize(buffer=nil, loop=false, pitch=1, volume=100, x=0, y=0, z=0) - Creates a Sound object using the specified sound buffer and other parameters
- to_s - Returns a formatted string representing this object (for debugging purposes)
- buffer, buffer= - Gets/sets this sound object's SFML::SoundBuffer.
- loop, loop= - Gets/sets the loop flag for this sound object.
- pitch, pitch= - Gets/sets the pitch for this sound object.
- volume, volume= - Gets/sets the volume for this sound object.
- position, position= - Gets/sets the position for this sound object (using an array of 3 numbers).
- status - Gets the status of this sound object (Sound::Stopped, Sound::Paused, Sound::Playing).
- playingOffset - Gets the current playing position of the sound (in seconds).
- play - Starts playing the sound.
- pause - Pauses the sound.
- stop - Stops playing the sound.

#### SFML::SoundBuffer

- initialize() - Default constructor
- initialize(soundBuffer) - Creates a copy of a SoundBuffer object.
- initialize(path) - Loads a sound file using the specified path (raises a RuntimeError on failure).
- to_s - Returns a formatted string representing this object (for debugging purposes)
- samples - Gets the raw (binary) samples as a Ruby string.
- samplesCount - Gets the total number of samples (shorts) returned by the samples call.
- samplesRate - Gets the sample rate (or number of samples per second for each channel).
- channels - Gets the number of channels (1=mono, 2=stereo).
- duration - Gets the duration of the sound buffer (in seconds).
- loadFromFile(path) - Loads a sound file using the specified path (returns false on failure).
- saveToFile(path) - Saves a sound file to the specified path (returns false on failure).
- loadFromMemory(samples, samplesCount, channels, sampleRate) - Builds a SoundBuffer from raw (binary) samples.

#### SFML::SoundBufferRecorder

- initialize() - Default constructor
- canCapture - (static) Returns true if the current system is capable of sound capture
- start(sampleRate=44100) - Starts the sound capture
- stop - Stops the sound capture
- buffer - Gets the SoundBuffer object containing the captured audio
- sampleRate - Gets the current sample rate

#### SFML::Sprite

- (Inherits all methods from SFML::Drawable)
- initialize() - Default constructor
- initialize(image, left=0, top=0, scale=1, rotation=0, c=Color.White) - Builds a Sprite object with the specified image and other options (scale can take one number or an array of two numbers)
- to_s - Returns a formatted string representing this object (for debugging purposes)
- width, w - Gets the sprite's width (affected by subRect and scale)
- height, h - Gets the sprite's height (affected by subRect and scale)
- right, right= - Gets/sets the right x position
- bottom, bottom= - Gets/sets the bottom y position
- x, x= - Gets/sets the center x position
- y, y= - Gets/sets the center y position
- image, image= - Gets/sets the image to use for this sprite
- subRect, subRect= - Gets/sets a rectangle within the image to use (generally used for tiled images)
- getPixel(x,y), [x,y] - Gets the color of a pixel within the sprite's subRect of the sprite's image ([0,0] would be the top-left pixel of the subRect)
- radius - Gets the bounding radius of the sprite (based on height and width)
- distance(sprite) - Gets the distance between the center positions of two sprites
- render(window) - (virtual) Override to add custom rendering code

#### SFML::Text

- (Inherits all methods from SFML::Drawable)
- initialize(str="", font="", size=32) - Initialize the Text object to the specified string, font, and font size.
- preloadFont(font, size) - (static) Call this to force the font to be loaded before the first time it gets rendered.
- text, text= - Gets/sets the current text string.
- font, font= - Gets/sets the current font.
- size, size= - Gets/sets the current font size.
- getRect - Gets the current screen rectangle.
- render(window) - (virtual) Override to add custom rendering code

#### SFML::VideoMode

- initialize() - Default constructor
- initialize(w, h, bpp=32) - Creates a VideoMode with the specified width, height, and bits-per-pixel.
- desktop - (static) Returns the VideoMode for the current desktop.
- each - (static) Iterates through all valid full-screen video modes.
- to_s - Returns a formatted string representing this object (for debugging purposes)
- width, w, width=, w= - Gets/sets the current width of this VideoMode.
- height, h, height=, h= - Gets/sets the current height of this VideoMode.
- bitsPerPixel, bpp, bitsPerPixel=, bpp= - Gets/sets the current bits-per-pixel of this VideoMode.
- isValid - Returns true if the current VideoMode is a valid full-screen mode.

#### SFML::View

- initialize() - Default constructor
- initialize(left, top, width, height, zoom=1) - Initializes all View members
- to_s - Returns a formatted string representing this object (for debugging purposes)
- left, l, left=, l= - Gets/sets the left x position for the view
- top, t, top=, t= - Gets/sets the top y position for the view
- width, w, width=, w= - Gets/sets the width for the view
- height, h, height=, h= - Gets/sets the height for the view
- zoom, zoom= - Gets/sets the zoom factor for the view

#### SFML::Window

- initialize(mode, title, style=Window::Resizable, antialias=0) - Creates a window using the specified VideoMode, title, and style
- to_s - Returns a formatted string representing this object (for debugging purposes)
- width, w - Gets the width of the window
- height, h - Gets the height of the window
- input - Gets the SFML::Input object for this window
- frameTime - Gets the amount of time it took to render the previous frame
- stencilBits - Gets the number of bits used in the stencil buffer
- depthBits - Gets the number of bits used in the back buffer
- getEvent - Returns the next event in the window's event queue (or nil if the queue is empty)
- useVerticalSync(bool) - Use to enable/disable vsync
- showMouseCursor(bool) - Use to show/hide the operating system's mouse cursor
- display - Call to swap the front and back buffers to display the frame
- setCurrent - Sets this window as the current target for rendering
- setFramerateLimit - Set a fixed framerate (use 0 to disable it)