ray 0.0.1 → 0.1.0.pre1

data/ext/vector.cpp

@@ -0,0 +1,215 @@
+#include "ray.hpp"
+
+VALUE ray_cVector2 = Qnil;
+VALUE ray_cVector3 = Qnil;
+
+ray_vector2 *ray_rb2vector2_ptr(VALUE obj) {
+   if (!RAY_IS_A(obj, ray_cVector2)) {
+      rb_raise(rb_eTypeError, "Can't convert %s into Ray::Vector2",
+               RAY_OBJ_CLASSNAME(obj));
+   }
+
+   ray_vector2 *vector;
+   Data_Get_Struct(obj, ray_vector2, vector);
+
+   return vector;
+}
+
+ray_vector2 ray_convert_to_vector2(VALUE obj) {
+   obj = rb_funcall(obj, RAY_METH("to_vector2"), 0);
+   return *ray_rb2vector2_ptr(obj);
+}
+
+void ray_free_vector2(ray_vector2 *ptr) {
+   delete ptr;
+}
+
+VALUE ray_alloc_vector2(VALUE self) {
+   ray_vector2 *vector = new ray_vector2;
+   return Data_Wrap_Struct(self, 0, ray_free_vector2, vector);
+}
+
+VALUE ray_vector2_to_rb(const ray_vector2 &vector) {
+   ray_vector2 *copy = new ray_vector2(vector);
+   return Data_Wrap_Struct(ray_cVector2, 0, ray_free_vector2, copy);
+}
+
+/*
+  @overload initialize(x = 0.0, y = 0.0)
+*/
+VALUE ray_init_vector2(int argc, VALUE *argv, VALUE self) {
+   ray_vector2 *vector = ray_rb2vector2_ptr(self);
+
+   VALUE x, y;
+   rb_scan_args(argc, argv, "02", &x, &y);
+
+   if (!NIL_P(x)) vector->x = NUM2DBL(x);
+   if (!NIL_P(y)) vector->y = NUM2DBL(y);
+
+   return self;
+}
+
+VALUE ray_init_vector2_copy(VALUE self, VALUE other) {
+   *ray_rb2vector2_ptr(self) = *ray_rb2vector2_ptr(other);
+   return self;
+}
+
+/* @return [Float] x position of the vector */
+VALUE ray_vector2_x(VALUE self) {
+   return rb_float_new(ray_rb2vector2_ptr(self)->x);
+}
+
+/* @return [Float] y position of the vector */
+VALUE ray_vector2_y(VALUE self) {
+   return rb_float_new(ray_rb2vector2_ptr(self)->y);
+}
+
+/* Sets the x position of the vector */
+VALUE ray_vector2_set_x(VALUE self, VALUE x) {
+   rb_check_frozen(self);
+
+   ray_rb2vector2_ptr(self)->x = NUM2DBL(x);
+   return x;
+}
+
+/* Sets the y position of the vector */
+VALUE ray_vector2_set_y(VALUE self, VALUE y) {
+   rb_check_frozen(self);
+
+   ray_rb2vector2_ptr(self)->y = NUM2DBL(y);
+   return y;
+}
+
+ray_vector3 *ray_rb2vector3_ptr(VALUE obj) {
+   if (!RAY_IS_A(obj, ray_cVector3)) {
+      rb_raise(rb_eTypeError, "Can't convert %s into Ray::Vector3",
+               RAY_OBJ_CLASSNAME(obj));
+   }
+
+   ray_vector3 *vector;
+   Data_Get_Struct(obj, ray_vector3, vector);
+
+   return vector;
+}
+
+ray_vector3 ray_convert_to_vector3(VALUE obj) {
+   obj = rb_funcall(obj, RAY_METH("to_vector3"), 0);
+   return *ray_rb2vector3_ptr(obj);
+}
+
+void ray_free_vector3(ray_vector3 *ptr) {
+   delete ptr;
+}
+
+VALUE ray_alloc_vector3(VALUE self) {
+   ray_vector3 *vector = new ray_vector3;
+   return Data_Wrap_Struct(self, 0, ray_free_vector3, vector);
+}
+
+VALUE ray_vector3_to_rb(const ray_vector3 &vector) {
+   ray_vector3 *copy = new ray_vector3(vector);
+   return Data_Wrap_Struct(ray_cVector3, 0, ray_free_vector3, copy);
+}
+
+/*
+  @overload initialize(x = 0.0, y = 0.0, z = 0.0)
+*/
+VALUE ray_init_vector3(int argc, VALUE *argv, VALUE self) {
+   ray_vector3 *vector = ray_rb2vector3_ptr(self);
+
+   VALUE x, y, z;
+   rb_scan_args(argc, argv, "03", &x, &y, &z);
+
+   if (!NIL_P(x)) vector->x = NUM2DBL(x);
+   if (!NIL_P(y)) vector->y = NUM2DBL(y);
+   if (!NIL_P(z)) vector->z = NUM2DBL(z);
+
+   return self;
+}
+
+VALUE ray_init_vector3_copy(VALUE self, VALUE other) {
+   *ray_rb2vector3_ptr(self) = *ray_rb2vector3_ptr(other);
+   return self;
+}
+
+/* The x position of the vector */
+VALUE ray_vector3_x(VALUE self) {
+   return rb_float_new(ray_rb2vector3_ptr(self)->x);
+}
+
+/* The y position of the vector */
+VALUE ray_vector3_y(VALUE self) {
+   return rb_float_new(ray_rb2vector3_ptr(self)->y);
+}
+
+/* The z position of the vector */
+VALUE ray_vector3_z(VALUE self) {
+   return rb_float_new(ray_rb2vector3_ptr(self)->z);
+}
+
+/* Sets the x position of the vector */
+VALUE ray_vector3_set_x(VALUE self, VALUE x) {
+   rb_check_frozen(self);
+   ray_rb2vector3_ptr(self)->x = NUM2DBL(x);
+   return x;
+}
+
+/* Sets the y position of the vector */
+VALUE ray_vector3_set_y(VALUE self, VALUE y) {
+   rb_check_frozen(self);
+   ray_rb2vector3_ptr(self)->y = NUM2DBL(y);
+   return y;
+}
+
+/* Sets the z position of the vector */
+VALUE ray_vector3_set_z(VALUE self, VALUE z) {
+   rb_check_frozen(self);
+   ray_rb2vector3_ptr(self)->z = NUM2DBL(z);
+   return z;
+}
+
+/*
+  Document-class: Ray::Vector2
+
+  This class can be used to represent either a point (x, y) or a size WxH
+  (hence the aliases).
+*/
+
+/*
+  Document-class: Ray::Vector3
+
+  Represents a point in a 3D space.
+*/
+
+void Init_ray_vector() {
+   ray_cVector2 = rb_define_class_under(ray_mRay, "Vector2", rb_cObject);
+   rb_define_alloc_func(ray_cVector2, ray_alloc_vector2);
+   rb_define_method(ray_cVector2, "initialize", ray_init_vector2, -1);
+   rb_define_method(ray_cVector2, "initialize_copy", ray_init_vector2_copy, 1);
+
+   rb_define_method(ray_cVector2, "x", ray_vector2_x, 0);
+   rb_define_method(ray_cVector2, "y", ray_vector2_y, 0);
+
+   rb_define_method(ray_cVector2, "x=", ray_vector2_set_x, 1);
+   rb_define_method(ray_cVector2, "y=", ray_vector2_set_y, 1);
+
+   ray_cVector3 = rb_define_class_under(ray_mRay, "Vector3", rb_cObject);
+   rb_define_alloc_func(ray_cVector3, ray_alloc_vector3);
+   rb_define_method(ray_cVector3, "initialize", ray_init_vector3, -1);
+   rb_define_method(ray_cVector3, "initialize_copy", ray_init_vector3_copy, 1);
+
+   rb_define_method(ray_cVector3, "x", ray_vector3_x, 0);
+   rb_define_method(ray_cVector3, "y", ray_vector3_y, 0);
+   rb_define_method(ray_cVector3, "z", ray_vector3_z, 0);
+
+   rb_define_method(ray_cVector3, "x=", ray_vector3_set_x, 1);
+   rb_define_method(ray_cVector3, "y=", ray_vector3_set_y, 1);
+   rb_define_method(ray_cVector3, "z=", ray_vector3_set_z, 1);
+}
+
+
+
+
+
+
+

data/guide.md

@@ -0,0 +1,619 @@
+# Installation
+## SFML
+
+You can possibly install the SFML 2 using your packag manager. For instance,
+with Archlinux:
+
+    yaourt -S sfml2-svn
+
+Otherwise, download [the SFML](http://www.sfml-dev.org/download.php) and build
+it, like:
+
+    cd sfml2
+    cmake .
+    make
+    make install # as root
+
+## Ray
+
+The ray gem is currently an older version of Ray. You can get the latest
+one from github:
+
+    git clone git://github.com/Mon-Ouie/ray.git
+    cd ray
+    rake install
+
+Ray should work on at least Linux, Window, and Mac OS X, with Ruby 1.8.7,
+1.9.2 and Rubinius.
+
+# Hello world!
+Here's a simple "Hello world!" written with ray:
+
+    require 'ray'
+    screen = Ray.create_window(:w => 100, :h => 100).fill(Ray::Color.black)
+    Ray::Font.default.draw("Hello world!", :on => screen, :size => 12).update
+    sleep 5
+
+It simply creates a window of size 100x100, fills it with black, then draws
+"Hello world!" on it with size 12, with the upper-left corner of the text at (0, 0).
+The screen must be updated so the modifications appear. Notice methods like #fill, #draw,
+ #update, ... return the object they drew on, which allows to chain methods call.
+
+Unfortunately, we have to sleep for a few seconds, or the window will be closed
+directly, and no one would see it. To exit when the user does something (say,
+when he tries to close the window), we need to check for events. Here's the
+lowest level way to do it:
+
+    require 'ray'
+
+    screen = Ray.create_window(:w => 100, :h => 100)
+    event  = Ray::Event.new
+
+    while event.type != Ray::Event::TYPE_QUIT
+      event.poll!
+
+      screen.fill Ray::Color.black
+      Ray::Font.default.draw("Hello world!", :on => screen, :size => 12).update
+    end
+
+The difference between the previous example is that we are using an event
+object. As long as its type is not Ray::Event::TYPE_QUIT, we update the
+event object (event.poll! does it without blocking the process) and
+redraw the screen.
+
+Ray has another way of doing this, though. It uses scenes and games objects.
+A scene is an object checking events to draw something on screen, and a
+game creates a window and handles a stack of scenes. Both kinds of
+objects can register blocks or callable objects to some event.
+
+    require 'ray'
+
+    Ray.game "Hello world!", :size => [100, 100] do
+      register do
+        add_hook :quit, method(:exit!)
+      end
+
+      scene :hello do
+        @font = Ray::Font.default
+
+        render do |screen|
+          @font.draw("Hello world!", :on => screen, :size => 12)
+        end
+      end
+
+      push_scene :hello
+    end
+
+Ray.game requires you to give the name of your game, which will be used as
+the title of the window. You can then specify the size of the window,
+100x100 in this case.
+
+In this block, self is the game object. After the end of the block, the game
+will be automatically run.
+
+The game object needs to register to some events. This must be done in a block,
+which will be called whenever the game object needs to register for events again.
+In this case, I used add_hook with a callable object. It is (almost) equivalent
+to the following:
+
+    on(:quit) { exit! }
+
+Then, we can specify the scenes used by the game, using #scene. In the block we
+passed to it, self would be our scene object. We can specify how to render
+our scene from there.
+
+Lastly, it is required to add a scene to the game's stack. A game runs as long
+as there are scenes in its stack.
+
+# Images
+
+Images are the first objects used, even in a Hello world. The screen itself
+is represented as an image object. They can be drawn, and one can draw on
+them.
+
+You can generate them programatically...
+
+    img = Ray::Image.new(:w => 100, :h => 100)
+    img.fill Ray::Color.blue
+    img.draw_line [0, 0], [50, 50], Ray::Color.green
+    img.draw_filled_ellipse [20, 20], 10, 15, Ray::Color.white
+    img.update # Or you won't see anything.
+
+... or from a file...
+
+    img = Ray::Image.new("some_file.png")
+
+... or from some data stored in memory.
+
+    require 'open-uri'
+    img = open("https://github.com/favicon.png") { |io| Ray::Image.new(io) }
+
+Then, the image can simply drawn on another one:
+
+    img.draw(:on => screen, :at => [30, 30])
+
+## Pixel access
+You can read inidividual pixels of an image using #[]:
+
+    img[15, 15] # => RGBA(...)
+
+It returns a Ray::Color object, on which you can call #r, #g, #b, and #a
+or #red, #green, #blue, and #alpha (alpha is the opacity, 255 is opaque).
+
+Similarily, you can use #[]= to change the color of a pixel /if/ the image
+is locked. To lock it you can use #lock and #unlock or just #lock with a
+block:
+    img.lock { img[15, 15] = Ray::Color.new(rand(256), rand(256), rand(256)) }
+
+(You don't need to call #update after #unlock)
+
+So, your images are basically collections of pixels. Therefore...
+
+    img.each do |color|
+      puts color
+    end
+
+    # map returns an image, not an array.
+    another_img = img.map do |color|
+      Ray::Color.new(0, 0, color.b)
+    end
+
+    img.map_with_pos! do |color, x, y|
+      Ray::Color.new(x, y, color.b)
+    end
+
+# Sprites
+
+Ray::Image#draw accepts many options: :on, :at, :rect, :shader, :color, :zoom,
+:angle, ... and sometimes, you will just always draw the image with the same
+parameters. Having an object storing those parameters is useful, and it's
+the purpose of the sprite class. It is pretty simple to create one:
+
+    sprite = Ray::Sprite.new(image, :angle => 30)
+    sprite = Ray::Sprite.new("some_file.png")
+
+There are also accessors for the attributes of the sprite:
+
+    sprite.color = Ray::Color.green
+    sprite.pos   = [3, 4]
+    sprite.pos # => Vector2[3, 4]
+
+Then you can draw an image using #draw_on:
+
+    sprite.draw_on some_image
+
+## Using sprite sheets
+
+Often, big images containing several parts which are displayed
+individually are used. You could just select the rect you want
+to display manually:
+
+     sprite.from_rect = Ray::Rect.new(32, 64, 32, 32)
+
+Ray also allows you to specify that there are, say, 3 cells
+of equal width on each line, and 4 lines height in the image:
+
+     sprite.sheet_size = [3, 4]
+
+Then, you could select the cell at (1, 2):
+
+     sprite.sheet_pos = [1, 2]
+
+# Shapes
+
+As shown, you can draw several shapes on an image using methods
+like #draw\_circle or #draw\_filled_rect. You can also create more
+complex polygons (NB: A circle is a polygon with many sides ; an
+ellipse is a stretched circle) using the Shape class.
+
+The shape itself has its own attributes:
+
+  * A scale factor
+  * The width of the outline
+  * Whether the shape is filled and the outline is visible
+
+    shape.scale = [3, 0.5]
+    shape.outline_width = 10
+    shape.filled = true
+    shape.outlined = false
+
+And each point of a shape has a few attributes:
+
+  * Its position
+  * Its color
+  * The color of its outline
+
+You can add a point with the required attributes using #add_point:
+
+    shape.add_point [0, 0]
+    shape.add_point [0, 0], Ray::Color.green
+    shape.add_point [0, 0], Ray::Color.green, Ray::Color.red
+
+Or even use Shape.new's block form:
+
+    Ray::Shape.new(10) do |point|
+      p point.id # => Something in 0..9
+
+      point.pos   = [3, 4]
+      point.color = Ray::Color.green
+    end
+
+Draw the shape on an image is similar to drawing a sprite:
+
+    shape.draw_on image
+
+# Text drawing
+
+Fonts are used to draw text. Apart from the default font, you can create
+a font from a file:
+
+    font = Ray::Font.new("file.ttf")
+    font = open("file.ttf") { |io| Ray::Font.new(io) }
+
+Then you can just draw text using Font#draw:
+
+    some_font.draw(some_string, :on => some_image, :at => some_pos, :size => 12)
+
+You can also specify the style with an array containing one or more of the
+following symbols as the :style parameter:
+
+  * :bold
+  * :italic
+  * :underline
+
+In Ruby 1.8, unless your string is UTF-8 encoded, you may want to specify
+the actual encoding you're using with the :encoding parameter.
+
+As you may need to compute the position of a text before drawing it, it is
+possible to get the size it uses with a given set of options:
+
+    font.size_of("Hello", :size => 12)
+
+## Using text objects
+
+Ray::Font#draw has, like Ray::Image#draw, many options. Simarily, a class
+keeping those parameters to draw text exists: Ray::Text.
+
+They can be created with a string, and some optional parameters:
+    text = Ray::Text.new "Hello world!", :at => [10, 10], :size => 30
+
+Their attributes can then be changed:
+    text.angle += 60
+
+And you can draw them on an image just like with sprite:
+    text.draw_on your_image
+
+# Games & Scenes
+## Parts of a scene
+The previous samples showed two parts in a scene: the setup code, and
+the rendering code.
+
+    scene :name do
+      # setup
+
+      render do |win|
+        # render
+      end
+    end
+
+Scenes are in fact more complex than that. A third important part is the
+always-block: it is used to execute code during every frame. For instance,
+the following scene draws an image moving to the right at every frame.
+
+    scene :moving_sprite do
+      self.frames_per_second = 30 # Framerate limitation
+
+      @sprite = sprite("image.png")
+
+      always do
+        @sprite.x += 1
+      end
+
+      render do |win|
+        @sprite.render_on win
+      end
+    end
+
+Scenes also have a clean up step, where you can remove references to objects
+that you don't need anymore so they can be garbage collected, or call methods
+to clean them up (like IO#close).
+
+    scene :clean_up do
+      @some_big_object = load_some_big_object
+
+      # ...
+
+      clean_up do
+        @some_big_object = nil
+      end
+    end
+
+## Scene flow
+It is likely an actual program will have to show more than a single scene. You
+can simply define more than one scene and use the push_scene and pop_scene methods.
+
+When a scene is popped, the previous scene is setup again. Sometimes, you may
+want to run a scene, and then just come back to wherever you ran the scene from.
+This is possible by using Scene#run_scene. Here's a more complex sample showing
+how it behaves:
+
+    require 'ray'
+
+    $stdout = StringIO.new
+
+    Ray.game "run_scene" do
+      register do
+        add_hook :quit, method(:exit!)
+
+        on :key_press, key(:up) do
+          puts "#{self} knows you pressed up"
+        end
+      end
+
+      font = Ray::Font.default
+
+      scene :sec do
+        on :key_press, key(:down) do
+          puts "#{self} knows you pressed down"
+        end
+
+        on :key_press, key(:left) do
+          pop_scene
+        end
+
+        puts "In scene :sec"
+
+        render do |win|
+          font.draw($stdout.string, :on => win, :size => 12)
+        end
+      end
+
+      scene :first do
+        on :key_press, key(:left) do
+          puts "#{self} knows you pressed left"
+        end
+
+        on :key_press, key(:right) do
+          run_scene :sec
+          puts "Back to scene :first"
+        end
+
+        puts "In scene :first"
+
+        render do |win|
+          font.draw($stdout.string, :on => win, :size => 12)
+        end
+      end
+
+      push_scene :first
+    end
+
+Another feature of scenes is their argument list. You could have a menu and using
+it in several places with different elements, without creating two scenes, by using
+scene arguments instead.
+
+    scene :menu do |elements|
+      # ...
+    end
+
+    push_scene :menu, %w[Hello world]
+    push_scene :menu, %w[This works too]
+
+## Handling input
+
+Scenes raise several events related to what the user is doing, here are a few:
+    on :key_press, key(:left) do |key, mod_keys|
+    end
+
+    on :window_resize do |size|
+    end
+
+    on :joy_press, 0, more_than(3) do |joy_id, button_id|
+    end
+
+You can see all the events raised in Ray::DSL::EventTranslator.
+
+Aside from those events, it is always possible to know the position of the
+mouse, and whether or not a key is being held.
+
+    holding? key(:left)
+    mouse_x
+    mouse_y
+
+## Event groups
+
+Sometimes, in the same scene, you'll want to disable some event handlers. For instance,
+in a game, when a menu is shown, you'd want the arrows to change the selected item
+instead of moving the character. To accomplish this in Ray, one could use event
+groups:
+
+    event_group :player do
+      %w[up down left right].each do |dir|
+        on(:key_press, key(dir)) { move_to(dir) }
+      end
+    end
+
+    event_group :menu do
+      on(:key_press, key(:up))   { select_prev }
+      on(:key_press, key(:down)) { select_next }
+    end
+
+    disable_event_group :menu
+
+    on :key_press, key(:enter) do
+      if menu.shown?
+        menu.hide
+
+        enable_event_group   :player
+        disable_event_grroup :menu
+      else
+        menu.show
+
+        disable_event_group :player
+        enable_event_group  :menu
+      end
+    end
+
+Notice that, even though I used symbols to name event groups, this is not
+required. In fact, using the menu object itself as the event group identifier
+could sometimes be better than generating a string to identify each of them.
+
+## Subclassing Ray::Scene
+
+In a bigger programming, having all the scenes in the same file would be
+unmaintable. Using the DSL to define scenes is thus not requirde:
+
+    class YourScene < Ray::Scene
+      scene_name :your_scene
+
+      def setup(*arguments)
+        # load stuff
+      end
+
+      def register
+        # register for events
+      end
+
+      def render(win)
+        # render stuff on an image
+      end
+
+      def clean_up
+        # clean the scene
+      end
+    end
+
+Then, instead of calling the scene method you'd use YourScene.bind, as in:
+    Ray.game "some game" do
+      YourScene.bind(self)
+      push_scene :your_scene
+    end
+
+# Turtle Graphics
+
+Ray implements turtle graphics. You can just start drawing on an image using
+Ray::Image#turtle:
+
+    image.turtle do
+      # self is a turtle!
+    end
+
+Then you can move forward or backward, turn left or right, change the color
+the pen, ...
+
+    image.turtle do
+      backward 10
+      right 30
+      forward 10
+
+      self.pen_width = 10
+      self.color     = Ray::Color.red
+
+      forward 10
+    end
+
+# Shaders
+
+Ray has methods which allow you to use pixel shaders. Those are written in
+the GLSL language, which you need to know to use them.
+
+They can be created from files quite simply:
+
+    shader = Ray::Shader.new("file.c")
+
+You can also load them from an IO object, possible a StringIO:
+
+    shader = Ray::Shader.new StringIO.new(<<-EOF)
+      void main() {
+        /* Your shader! */
+      }
+    EOF
+
+They can be used to draw images, sprites, or shapes:
+
+    image.draw :on => other, :shader => your_shader
+    sprite.shader = your_shader
+    shape.draw :on => other, :shader => your_shader
+
+If you've enabled lazy rendering for scenes, you can also set a shader to be used
+whenever you're drawing your image to the screen:
+
+    self.lazy_rendering = true
+    self.shader = Ray::Shader.new("some_file")
+
+# OpenGL
+
+It is possible to use plain OpenGL to draw stuff when using Ray. To do so,
+you would of course need an OpenGL binding. Then you can use the Ray::Drawable
+class to draw stuff:
+
+    drawable = Ray::Drawable.new do |img|
+      # img is the image you are drawing on
+
+      # OpenGL rendering code here
+    end
+
+    drawable.draw_on image
+
+Ray automatically changes the projection matrix so (0, 0, 0) is the upper left
+corner, and (width, height, 0) the bottom down corner. Of course, you can change
+the matrix to whatever you want.
+
+## Using Ray's resources
+
+Ray can load images and shaders. If you want to draw a 3D cube, you can still use
+Ray's images. To do so, just call Ray::Image#bind. Similarily, you can use a shader
+by passing a block to Ray::Shader#bind.
+
+    drawable = Ray::Drawable.new do |img|
+      some_other_image.bind
+
+      some_shader.bind do
+        # Draw something using the previous image as a texture
+      end
+    end
+
+# Audio
+## Playing sound
+
+Ray uses two classes to play sounds: Ray::Sound and Ray::Music. The former is used
+for short sounds, and the latter to stream musics. They both have a very similar
+API. You can create them from files or IO objects:
+
+    sound = Ray::Sound.new("file.wav")
+    sound = open("file.wav") { |io| Ray::Sound.new(io) }
+
+    music = Ray::Music.new("file.wav")
+    music = open("file.wav") { |io| Ray::Music.new(io) }
+
+Then they can all be played, paused, or stopped:
+
+    sound.play
+    sound.pause
+    sound.stop
+
+They can be configured to play in a loop:
+
+    sound.loop = true
+
+Their volume can be changed:
+
+    sound.volume = 30 # (value between 0 and 100)
+
+## 3D sound effects
+
+It is possible to change several paremeters to give 3D sound effects.
+You can move the listener however you want:
+
+    Ray::Audio.position  = [3, -4, 2.5]
+    Ray::Audio.direction = [1, -2, 3]
+
+Same for the sounds which are played:
+
+    sound.position = [1, -3, 4]
+
+# More
+Ray's API is documented too. Check the documentation to know more about
+how to use it.
+
+There are also a few samples which you can find in the git repository.