ray 0.1.0.pre1 → 0.1.0

data/README.md

@@ -1,58 +1,261 @@
-# Hello world!
-## Subclassing Ray::Game or Ray::Scene
+What is Ray?
+============
+
+Ray is a library than can create windows, play music, and draw 2D graphics (or
+not too complex 3D by doing just a bit more work, thanks to OpenGL). It is meant
+to be easy and fun to use (à la Shoes), and still flexible and powerful.
+
+Tutorial & Installation
+=======================
+
+See [on this page](http://mon-ouie.github.com/projects/ray.html).
+
+Features
+========
+
+Fun DSL
+-------
+
     require 'ray'
 
-    class HelloScene < Ray::Scene
-      scene_name :hello
+    Ray.game "Hello" do
+      register { add_hook :quit, method(:exit!) }
+
+      scene :hello do
+        @text = text "Hello world!", :size => 30, :angle => 30, :at => [50, 50]
+        render { |win| win.draw @text }
+      end
+
+      scenes << :hello
+    end
+
+Flexible for more complex games
+-------------------------------
+
+    require 'ray'
+
+    class TitleScene < Ray::Scene
+      scene_name :title
 
       def setup
-        @font = font("VeraMono.ttf")
+        # setup resources
+      end
+
+      def register
+        # register for events
       end
 
       def render(win)
-        @font.draw("Hello world!", :on => win, :at => [0, 0], :size => 12)
+        # draw!
       end
+
+      def clean_up
+        # perform cleanup
+      end
+    end
+
+    class GameScene < Ray::Scene
+      scene_name :game
+
+      # same stuff
     end
 
-    class HelloWorld < Ray::Game
+    # ...
+
+    class Game < Ray::Game
       def initialize
-        super("Hello world!")
+        super "Awesome Game"
 
-        HelloScene.bind(self)
-        push_scene :hello
+        TitleScene.bind(self)
+        GameScene.bind(self)
+        # ...
+
+        scenes << :title
       end
+    end
 
-      def register
-        add_hook :quit, method(:exit!)
+Drawable API
+------------
+
+Ray has a drawable class that specifies a common interface to all the drawable
+objects – how to perform transformations to them and how to draw them.
+
+
+     obj = AnyDrawable.new
+
+     window.draw obj
+
+     obj.pos    = [0, 2]   # set position
+     obj.angle  = 40       # rotation
+     obj.origin = [20, 20] # just sets the origin of transformations
+     # ...
+
+     # You can even have a completely custom transformation matrix:
+     obj.matrix = Ray::Matrix.translation [2, 3, 4]
+
+Off-screen rendering
+--------------------
+
+When rendering to a window is not enough, you can render on an image just fine:
+
+    Ray::ImageTarget.new some_image do |target|
+      target.clear Ray::Color.red
+      target.draw Ray::Polygon.circle([50, 50], 10, Ray::Color.green)
+      target.update
+    end
+
+OpenGL integration
+------------------
+
+Ray uses OpenGL, and provides some classes and methods to allow using it from
+Ray. In fact, ``Ray::Drawable`` can simply be used for OpenGL rendering:
+
+    # Ray has a more advanced sprite class, of course!
+    class CustomSprite < Ray::Drawable
+      def initialize(image)
+        super() # very important: creating the actual drawable
+
+        # Ray allocates a VBO to store your vertices.
+        # You could just use your own OpenGL binding to call glBegin and glEnd
+        # if you don't want to use it.
+        self.vertex_count = 4
+
+        # Tells Ray to enable texturing for this drawable
+        self.textured = true
+
+        @image = image
+      end
+
+      # return an array of vertices
+      def fill_vertices
+        [
+         Ray::Vertex.new([0,      0],      Ray::Color.white, [0, 0]),
+         Ray::Vertex.new([@img.w, 0],      Ray::Color.white, [1, 0]),
+         Ray::Vertex.new([@img.w, @img.h], Ray::Color.white, [1, 1]),
+         Ray::Vertex.new([0,      @img.h], Ray::Color.white, [0, 1]),
+        ]
+      end
+
+      # The index parameter is there in case you'd want to use
+      # draw_elements. You can fill indices by defining a fill_indices method
+      # and setting index_count.
+      def render(first, index)
+        @image.bind
+
+        # Some low level OpenGL calls are available
+        Ray::GL.draw_arrays :triangle_fan, first, 4
       end
     end
 
-    HelloWorld.new.run
-## DSL
-    require 'ray'
+You can also create and use shaders from Ruby:
+
+    shader = Ray::Shader.new :vertex => "vertex_shader.glsl",
+                             :frag   => "frag_shader.glsl"
+    drawable.shader = shader
+
+    # You can't assign an image to a render target, but you can recompile it:
+    window.shader.compile :vertex => "vertex.glsl", :frag => "frag.glsl"
+
+3D rendering
+------------
+
+3D rendering is a very cool thing! Even if Ray's graphics module only uses 2D, a
+3D API can be created with it. You can just use ``Ray::Drawable`` again, but you
+will ned to specify the layout of your vertices and to write your own shaders
+(the default shaders are only designed for 2D). You will probably need a custom
+projection matrix too.
 
-    Ray::Game.new("Hello world!") do
-      register do
-        add_hook :quit, method(:exit!)
+    class Cube < Ray::Drawable
+      include Ray::GL
+
+      Vertex = Ray::GL::Vertex.make [
+        [:pos, "in_Position", :vector3],
+        [:col, "in_Color",    :color]
+      ]
+
+      def initialize
+        super Vertex
+        # ...
       end
 
-      scene :hello do
-        @font = font("VeraMono.ttf")
+      # ...
+    end
+
+    # ...
+
+    # Tell the shader what vertex layout to use.
+    window.shader.apply_vertex Cube::Vertex
+    window.shader.compile :vertex => "vertex.glsl", :frag => "frag.glsl"
+
+    # Ray::Matrix can create 3D transformation and projection matrices!
+    window.view = Ray::View.new Ray::Matrix.perspective(90, 1, 1, 100)
+
+Audio playback
+--------------
+
+Ray can play short sounds right away and stream longer ones — it uses OpenAL for
+this. 3D audio effects can be added as well.
 
-        render do |win|
-          @font.draw("Hello world", :on => win, :at => [0, 0], :size => 12)
-        end
+    @sound = sound "test.wav"
+    @music = music "test.ogg"
+
+    @sound.pause
+    @music.play
+
+    @music.pause
+
+    @music.volume = 80
+    @music.pitch  = 0.9
+    @music.pos    = [10, 20, 30]
+
+    @music.play
+
+Testing
+-------
+
+Ray's events can be faked so that you can simulate user input in your tests:
+
+    require 'awesome_scene'
+
+    describe AwesomeScene do
+      before :each do
+        @game = AwesomeGame.new
+        @scene = @game.registered_scene(:awesome_scene)
+
+        @scene.register
+        @scene.setup
+      end
+
+      it "has a cursor at (0, 0)" do
+        @scene.cursor.pos.should == [0, 0]
+      end
+
+      it "moves its cursor after the mouse moved" do
+        @game.raise_event :mouse_motion, Ray::Vector2[100, 100]
+        @game.event_runner.run
+
+        @scene.cursor.pos.should == [100, 100]
+      end
+
+      it "draws its cursor" do
+        @scene.window.should_receive(:draw, @scene.cursor)
+        @scene.render @scene.window
       end
 
-      push_scene :hello
+      after :each do
+        @scene.clean_up
+      end
     end
 
-# Features
-* Can hide the event loop where registred blocks or methods are run when something
-  happens.
-* Provides a cache for resources like images, fonts, sounds, ...
-* Implements turtle graphics
-* Nothing more serious than a toy.
+Animations
+----------
+
+You can animate the fact the state of an object is changing (its position, etc.)
+using Ray's animation objects:
+
+    animations << translation(:from => [0, 0], :to => [100, 100],
+                              :duration => 4).start(@some_drawable)
+
+(They can really be used to animate any change, not just those that are visible,
+and not just those applied to a drawable.)
 
-# Installation & Getting started
-See [the guide](guide.md)

data/Rakefile

@@ -1,9 +1,15 @@
 # -*- coding: utf-8 -*-
+
+begin
+  require 'devkit' # only used on windows
+rescue LoadError
+end
+
 begin
   require 'yard'
 
   YARD::Rake::YardocTask.new do |t|
-    t.files = ['lib/**/*.rb', 'ext/**/*.cpp']
+    t.files = ['lib/**/*.rb', 'ext/**/*.c']
     t.options |= ["--private", "-e", "./yard_ext.rb"]
   end
 rescue LoadError
@@ -11,69 +17,34 @@ rescue LoadError
                "with the following command: gem install yard")
 end
 
-begin
-  require 'jeweler'
-
-  Jeweler::Tasks.new do |s|
-    s.name = "ray"
-
-    s.summary = "A library to write games (or to play with) in Ruby"
-    s.description = "Written to play with Ruby"
-    s.homepage = "http://github.com/Mon-Ouie/ray"
-
-    s.email = "mon.ouie@gmail.com"
-    s.authors = ["Mon ouïe"]
-
-    s.files |= FileList["lib/**/*.rb"]
-    s.files |= FileList["ext/**/*.{cpp,h}"]
-    s.files |= FileList["*.md"]
-    s.files << ".gemtest" << "Rakefile"
-
-    s.has_rdoc = "yard"
-
-    s.extensions = ["ext/extconf.rb"]
-
-    s.add_development_dependency "jeweler"
-    s.add_development_dependency "yard"
-    s.add_development_dependency "riot"
-    s.add_development_dependency "rr"
-  end
-rescue LoadError
-  $stderr.puts("Jeweler is not installed. Please install it " +
-               "with the following command: gem intall jeweler")
-end
-
 namespace :ext do
   desc "Rebuilds the C extension"
   task :rebuild do
     cd "ext/"
-    sh "ruby extconf.rb && make clean && make"
+    ruby "extconf.rb" and sh "make clean && make"
   end
 
   desc "Builds the C extension"
   task :build do
     cd "ext/"
-    sh "ruby extconf.rb && make"
+    ruby "extconf.rb" and sh "make"
   end
 end
 
 desc "Builds the C extension"
 task :ext => ["ext:build"]
 
-desc "Starts IRB"
-task :irb do
-  require 'irb'
-  ARGV.clear
-
-  $:.unshift File.expand_path(File.join(File.dirname(__FILE__), "ext"))
-  $:.unshift File.expand_path(File.join(File.dirname(__FILE__), "lib"))
-
-  require 'ray'
-
-  IRB.start
-end
-
 desc "Runs tests"
 task :test do
-  load File.expand_path(File.join(File.dirname(__FILE__), "test", "run_all.rb"))
+  test_file = File.expand_path("test/run_all.rb", File.dirname(__FILE__))
+
+  begin
+    if defined?(RUBY_ENGINE) && RUBY_ENGINE == "jruby"
+      ruby "-X+O", test_file
+    else
+      ruby test_file
+    end
+  rescue
+    exit 1
+  end
 end

data/ext/audio.c

@@ -0,0 +1,68 @@
+#include "ray.h"
+
+VALUE ray_mAudio = Qnil;
+
+/*
+  @return [Float] The global volume. 0 is the minimum volume, whereas 100
+  is the maximum.
+*/
+VALUE ray_audio_volume(VALUE self) {
+  return rb_float_new(say_audio_get_volume());
+}
+
+/*
+  @overload volume=(val)
+  Sets the global volume.
+  @param [Float] val The new value for the volume.
+*/
+VALUE ray_audio_set_volume(VALUE self, VALUE value) {
+  float volume = (float)NUM2DBL(value);
+  say_audio_set_volume(volume);
+
+  return value;
+}
+
+/*
+  @return [Ray::Vector3] The position of the listener.
+*/
+VALUE ray_audio_pos(VALUE self) {
+  return ray_vector3_to_rb(say_audio_get_pos());
+}
+
+/*
+  @overload pos=(pos)
+  Sets the position of the listener.
+  @param [Ray::Vector3, #to_vector3] pos The new position of the
+  listener.
+*/
+VALUE ray_audio_set_pos(VALUE self, VALUE pos) {
+  say_audio_set_pos(ray_convert_to_vector3(pos));
+  return pos;
+}
+
+/*
+  @return [Ray::Vector3] The orientation of the listener.
+*/
+VALUE ray_audio_direction(VALUE self) {
+  return ray_vector3_to_rb(say_audio_get_direction());
+}
+
+/*
+  @overload direction=(dir)
+  Sets the orientation of the listener.
+  @param [Ray::Vector3, #to_vector3] dir The new orientation of the listener.
+*/
+VALUE ray_audio_set_direction(VALUE self, VALUE dir) {
+  say_audio_set_direction(ray_convert_to_vector3(dir));
+  return dir;
+}
+
+void Init_ray_audio() {
+  ray_mAudio = rb_define_module_under(ray_mRay, "Audio");
+  rb_define_module_function(ray_mAudio, "volume", ray_audio_volume, 0);
+  rb_define_module_function(ray_mAudio, "volume=", ray_audio_set_volume, 1);
+  rb_define_module_function(ray_mAudio, "pos", ray_audio_pos, 0);
+  rb_define_module_function(ray_mAudio, "pos=", ray_audio_set_pos, 1);
+  rb_define_module_function(ray_mAudio, "direction", ray_audio_direction, 0);
+  rb_define_module_function(ray_mAudio, "direction=", ray_audio_set_direction, 1);
+}