ray 0.1.1 → 0.2.0

data/README.md

@@ -8,7 +8,8 @@ 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).
+See [on this page](http://mon-ouie.github.com/projects/ray.html). Also notice
+there's an IRC channel on freenode: #ray.
 
 Features
 ========
@@ -128,11 +129,13 @@ Ray. In fact, ``Ray::Drawable`` can simply be used for OpenGL rendering:
 
       # return an array of vertices
       def fill_vertices
+        rect = @img.tex_rect [0, 0, @img.w, @img.h]
+
         [
-         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]),
+         Ray::Vertex.new([0,      0],      Ray::Color.white, rect.top_left),
+         Ray::Vertex.new([@img.w, 0],      Ray::Color.white, rect.top_right),
+         Ray::Vertex.new([0,      @img.h], Ray::Color.white, rect.bottom_left),
+         Ray::Vertex.new([@img.w, @img.h], Ray::Color.white, rect.bottom_right),
         ]
       end
 
@@ -143,7 +146,7 @@ Ray. In fact, ``Ray::Drawable`` can simply be used for OpenGL rendering:
         @image.bind
 
         # Some low level OpenGL calls are available
-        Ray::GL.draw_arrays :triangle_fan, first, 4
+        Ray::GL.draw_arrays :triangle_strip, first, 4
       end
     end
 

data/Rakefile

@@ -39,11 +39,7 @@ task :test do
   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
+    ruby test_file
   rescue
     exit 1
   end

data/ext/audio.c

@@ -3,18 +3,18 @@
 VALUE ray_mAudio = Qnil;
 
 /*
-  @return [Float] The global volume. 0 is the minimum volume, whereas 100
-  is the maximum.
-*/
+ * @see volume=
+ */
 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.
-*/
+ * @overload volume=(val)
+ *   Sets the global volume
+ *   @param [Float] val The new value for the volume, 0 being the minimum and
+ *     100 the maximum as well as the default.
+ */
 VALUE ray_audio_set_volume(VALUE self, VALUE value) {
   float volume = (float)NUM2DBL(value);
   say_audio_set_volume(volume);
@@ -23,17 +23,17 @@ VALUE ray_audio_set_volume(VALUE self, VALUE value) {
 }
 
 /*
-  @return [Ray::Vector3] The position of the listener.
-*/
+ * @see pos=
+ */
 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.
+ * @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));
@@ -41,22 +41,28 @@ VALUE ray_audio_set_pos(VALUE self, VALUE pos) {
 }
 
 /*
-  @return [Ray::Vector3] The orientation of the listener.
-*/
+ * @see direction=
+ */
 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.
-*/
+ * @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;
 }
 
+/*
+ * Document-class: Ray::Audio
+ *
+ * Ray.:Audio is used to manipulate the state of the listener, through global
+ * parameters such as volume or position in the 3D world.
+ */
 void Init_ray_audio() {
   ray_mAudio = rb_define_module_under(ray_mRay, "Audio");
   rb_define_module_function(ray_mAudio, "volume", ray_audio_volume, 0);

data/ext/audio_source.c

@@ -15,8 +15,7 @@ say_audio_source *ray_rb2audio_source(VALUE obj) {
   return NULL;
 }
 
-
-/* @return [Float] Volume of the source, between 0 and 100. */
+/* @see volume= */
 static
 VALUE ray_audio_source_volume(VALUE self) {
   say_audio_source *source = ray_rb2audio_source(self);
@@ -24,10 +23,14 @@ VALUE ray_audio_source_volume(VALUE self) {
 }
 
 /*
-  @overload volume=(vol)
-  Sets the volume of the source.
-  @param [Float] vol The new volume of the source.
-*/
+ *  @overload volume=(vol)
+ *    Sets the volume of the source
+ *
+ *    The volume is a number between 0 and 100. When it is set to 100, the
+ *    volume is maximal.
+ *
+ *    @param [Float] vol The new volume of the source
+ */
 static
 VALUE ray_audio_source_set_volume(VALUE self, VALUE value) {
   rb_check_frozen(self);
@@ -38,7 +41,7 @@ VALUE ray_audio_source_set_volume(VALUE self, VALUE value) {
   return value;
 }
 
-/* @return [Float] The pitch of the source. */
+/* @see ptich= */
 static
 VALUE ray_audio_source_pitch(VALUE self) {
   say_audio_source *source = ray_rb2audio_source(self);
@@ -46,11 +49,14 @@ VALUE ray_audio_source_pitch(VALUE self) {
 }
 
 /*
-  @overload pitch=(pitch)
-    Sets the pitch of the sound.
-    @param [Float] pitch the pitch value, which makes a sound more acute
-      or grave and also affects playing speed. Defaulted to 1.
-*/
+ * @overload pitch=(pitch)
+ *   Sets the pitch of the sound
+ *
+ *   Pitch makes the sound more acute or grave, and affcets playing speed. It is
+ *   defaulted to 1.
+ *
+ *   @param [Float] pitch The new pitch value
+ */
 static
 VALUE ray_audio_source_set_pitch(VALUE self, VALUE pitch) {
   rb_check_frozen(self);
@@ -61,7 +67,7 @@ VALUE ray_audio_source_set_pitch(VALUE self, VALUE pitch) {
   return pitch;
 }
 
-/* @return [Ray::Vector3] The position of the source. */
+/* @see pos= */
 static
 VALUE ray_audio_source_pos(VALUE self) {
   say_audio_source *source = ray_rb2audio_source(self);
@@ -69,10 +75,10 @@ VALUE ray_audio_source_pos(VALUE self) {
 }
 
 /*
-  @overload pos=(pos)
-    Sets the position of the sound.
-    @param [Ray::Vector3, #to_vector3] pos The position of the source.
-*/
+ * @overload pos=(pos)
+ *   Sets the position of the sound
+ *   @param [Ray::Vector3] pos The new position of the source
+ */
 static
 VALUE ray_audio_source_set_pos(VALUE self, VALUE pos) {
   rb_check_frozen(self);
@@ -84,9 +90,8 @@ VALUE ray_audio_source_set_pos(VALUE self, VALUE pos) {
 }
 
 /*
-  @return [true, false] True if the source position is relative to the listener,
-  as opposed to being absolute.
-*/
+ * @see relative=
+ */
 static
 VALUE ray_audio_source_is_relative(VALUE self) {
   say_audio_source *source = ray_rb2audio_source(self);
@@ -94,11 +99,13 @@ VALUE ray_audio_source_is_relative(VALUE self) {
 }
 
 /*
-  @overload relative=(rel)
-    Sets whether the sound should be relative.
-    @param [true, false] rel Whether the source position should be relative
-      to the listener's.
-*/
+ *@overload relative=(rel)
+ *  Sets whether the sound position is relative to the listener's
+ *
+ *  This is false by default, meaning the position is absolute.
+ *
+ *  @param [true, false] rel True to make the sound become relative
+ */
 static
 VALUE ray_audio_source_set_relative(VALUE self, VALUE val) {
   rb_check_frozen(self);
@@ -109,7 +116,7 @@ VALUE ray_audio_source_set_relative(VALUE self, VALUE val) {
   return val;
 }
 
-/* @return [Float] the source's minimal distance. */
+/* @see min_distance= */
 static
 VALUE ray_audio_source_min_distance(VALUE self) {
   say_audio_source *source = ray_rb2audio_source(self);
@@ -117,11 +124,14 @@ VALUE ray_audio_source_min_distance(VALUE self) {
 }
 
 /*
-  @overload min_distance=(dist)
-    Sets the sounds minimal distance.
-    @param [Float] dist the distance beyond which the source's volume will
-      decrease. Defaulted to 1.
-*/
+ * @overload min_distance=(dist)
+ *   Sets the sounds minimal distance
+ *
+ *   The minimal distance is the distance beyound which a source's volume will
+ *   start decreasing. It is defaulted to one.
+ *
+ *   @param [Float] dist The new default value
+ */
 static
 VALUE ray_audio_source_set_min_distance(VALUE self, VALUE dist) {
   rb_check_frozen(self);
@@ -132,7 +142,7 @@ VALUE ray_audio_source_set_min_distance(VALUE self, VALUE dist) {
   return dist;
 }
 
-/* @return [Float] The source's attenuation */
+/* @see attenuation= */
 static
 VALUE ray_audio_source_attenuation(VALUE self) {
   say_audio_source *source = ray_rb2audio_source(self);
@@ -140,12 +150,14 @@ VALUE ray_audio_source_attenuation(VALUE self) {
 }
 
 /*
-  @overload attenuation=(attenuation)
-    Sets the attenuation of a sound.
-    @param [Float] atenuation New attenuation factor of the sound.
-      0 will prevent the sound from being attenuated, 100 would
-      make the sound be attenuated much more quickly.
-*/
+ *  @overload attenuation=(attenuation)
+ *    Sets the attenuation of a sound
+ *
+ *    When set to 0, the sound will not be attenuated at all. 100 makes
+ *    attenuation very quick.
+ *
+ *    @param [Float] atenuation New attenuation factor of the sound
+ */
 static
 VALUE ray_audio_source_set_attenuation(VALUE self, VALUE att) {
   rb_check_frozen(self);
@@ -153,7 +165,13 @@ VALUE ray_audio_source_set_attenuation(VALUE self, VALUE att) {
   return att;
 }
 
-/* @return [Symbol] Playing status. One of playing, paused, stopped. */
+/*
+ * Playing status
+ *
+ * The status can be +:playing+, +:paused+, or +:stopped+.
+ *
+ * @return [Symbol] Playing status
+ */
 static
 VALUE ray_audio_source_status(VALUE self) {
   switch (say_audio_source_get_status(ray_rb2audio_source(self))) {
@@ -165,6 +183,14 @@ VALUE ray_audio_source_status(VALUE self) {
   return Qnil; /* should never happen */
 }
 
+/*
+ * Document-class: Ray::AudioSource
+ *
+ * Audio sources are objects able to produce sound, either by directly passing
+ * them to a buffer or by streaming audio data.
+ *
+ * This class holds generic methods to manipulate a source.
+ */
 void Init_ray_audio_source() {
   ray_cAudioSource = rb_define_class_under(ray_mRay, "AudioSource", rb_cObject);
 
@@ -174,6 +200,7 @@ void Init_ray_audio_source() {
   rb_define_method(ray_cAudioSource, "pitch", ray_audio_source_pitch, 0);
   rb_define_method(ray_cAudioSource, "pitch=", ray_audio_source_set_pitch, 1);
 
+  /* @group Spatialization */
   rb_define_method(ray_cAudioSource, "pos", ray_audio_source_pos, 0);
   rb_define_method(ray_cAudioSource, "pos=",
                    ray_audio_source_set_pos, 1);
@@ -192,6 +219,7 @@ void Init_ray_audio_source() {
                    ray_audio_source_attenuation, 0);
   rb_define_method(ray_cAudioSource, "attenuation=",
                    ray_audio_source_set_attenuation, 1);
+  /* @endgroup */
 
   rb_define_method(ray_cAudioSource, "status", ray_audio_source_status, 0);
 }

data/ext/color.c

@@ -29,10 +29,10 @@ VALUE ray_color_alloc(VALUE self) {
 }
 
 /*
-  @overload initialize(red, green, blue, alpha = 255)
-    Creates a new color. All the parameters must be integers between
-    0 and 255. Alpha is the transparency (255: opaque, 0: invisible).
-*/
+ * @overload initialize(red, green, blue, alpha = 255)
+ *   Creates a new color. All the parameters must be integers between
+ *     0 and 255. Alpha is the transparency (255: opaque, 0: invisible).
+ */
 static
 VALUE ray_color_init(int argc, VALUE *argv, VALUE self) {
   VALUE r, g, b, a;
@@ -98,10 +98,10 @@ VALUE ray_color_a(VALUE self) {
 }
 
 /*
-  @overload r=(val)
-    Sets the red intensity.
-    @param [Integer] The new red intensity.
-*/
+ *  @overload r=(val)
+ *    Sets the red intensity
+ *    @param [Integer] The new red intensity.
+ */
 static
 VALUE ray_color_set_r(VALUE self, VALUE val) {
   rb_check_frozen(self);
@@ -114,9 +114,9 @@ VALUE ray_color_set_r(VALUE self, VALUE val) {
 }
 
 /*
-  @overload r=(val)
-    Sets the red intensity.
-    @param [Integer] The new red intensity.
+ * @overload g=(val)
+ *   Sets the green intensity
+ *   @param [Integer] The new green intensity.
 */
 static
 VALUE ray_color_set_g(VALUE self, VALUE val) {
@@ -130,10 +130,10 @@ VALUE ray_color_set_g(VALUE self, VALUE val) {
 }
 
 /*
-  @overload b=(val)
-    Sets the blue intensity.
-    @param [Integer] The new blue intensity.
-*/
+ * @overload blue=(val)
+ *   Sets the blue intensity
+ *   @param [Integer] The new blue intensity.
+ */
 static
 VALUE ray_color_set_b(VALUE self, VALUE val) {
   rb_check_frozen(self);
@@ -146,10 +146,10 @@ VALUE ray_color_set_b(VALUE self, VALUE val) {
 }
 
 /*
-  @overload a=(val)
-    Sets the alpha opacity.
-    @param [Integer] The new alpha opacity.
-*/
+ * @overload a=(val)
+ *   Sets the alpha opacity
+ *   @param [Integer] The new alpha opacity.
+ */
 static
 VALUE ray_color_set_a(VALUE self, VALUE val) {
   rb_check_frozen(self);

data/ext/drawable.c

@@ -2,6 +2,19 @@
 
 VALUE ray_cDrawable = Qnil;
 
+static
+void ray_drawable_actual_matrix_proc(void *data, say_matrix *matrix) {
+  say_drawable *drawable = ((ray_drawable*)data)->drawable;
+
+  VALUE rb_obj = (VALUE)say_drawable_get_other_data(drawable);
+  VALUE proc   = rb_iv_get(rb_obj, "@matrix_proc");
+
+  VALUE rb_matrix = rb_funcall(proc, RAY_METH("call"), 1, rb_obj);
+
+  memcpy(matrix->content, ray_rb2matrix(rb_matrix)->content,
+         sizeof(say_matrix));
+}
+
 static
 void ray_drawable_fill_proc(void *drawable_ptr, void *vertex_ptr) {
   ray_drawable *drawable = drawable_ptr;
@@ -27,9 +40,22 @@ void ray_drawable_fill_proc(void *drawable_ptr, void *vertex_ptr) {
   }
 }
 
+void ray_drawable_shader_proc(void *data, say_shader *shader) {
+  /* Works because the offset will be the same anyway */
+  say_drawable *drawable = ((ray_drawable*)data)->drawable;
+
+  VALUE rb_obj = (VALUE)say_drawable_get_other_data(drawable);
+  VALUE hash   = rb_iv_get(rb_obj, "@shader_attributes");
+
+  if (!NIL_P(hash)) {
+    /* Create a ruby shader object to call merge */
+    VALUE rb_shader = ray_shader2rb(shader, Qnil);
+    rb_funcall(rb_shader, RAY_METH("merge"), 1, hash);
+  }
+}
+
 static
-void ray_drawable_render_proc(void *data, size_t first, size_t index,
-                              say_shader *shader) {
+void ray_drawable_render_proc(void *data, size_t first, size_t index) {
   ray_drawable *drawable = (ray_drawable*)data;
   rb_funcall(drawable->obj, RAY_METH("render"), 2,
              ULONG2NUM(first), ULONG2NUM(index));
@@ -60,16 +86,16 @@ void ray_drawable_indices_fill_proc(void *data, GLuint *ptr, size_t first) {
   VALUE array = rb_funcall(drawable->obj, RAY_METH("fill_indices"), 1,
                            ULONG2NUM(first));
 
-  say_array *c_array     = ray_rb2int_array(array);
+  mo_array *c_array      = ray_rb2int_array(array);
   size_t     size        = say_drawable_get_index_count(drawable->drawable);
-  size_t     actual_size = say_array_get_size(c_array);
+  size_t     actual_size = c_array->size;
 
-  if (say_array_get_size(c_array) < size) {
+  if (actual_size < size) {
     rb_raise(rb_eRuntimeError, "received %zu indices, expected %zu",
              actual_size, size);
   }
 
-  memcpy(ptr, say_array_get(ray_rb2int_array(array), 0), sizeof(GLuint) * size);
+  memcpy(ptr, mo_array_at(c_array, 0), sizeof(GLuint) * size);
 }
 
 say_drawable *ray_rb2drawable(VALUE obj) {
@@ -126,7 +152,9 @@ VALUE ray_drawable_init(int argc, VALUE *argv, VALUE self) {
 
   obj->drawable = say_drawable_create(id);
   say_drawable_set_custom_data(obj->drawable, obj);
+  say_drawable_set_other_data(obj->drawable, (void*)self);
   say_drawable_set_fill_proc(obj->drawable, ray_drawable_fill_proc);
+  say_drawable_set_shader_proc(obj->drawable, ray_drawable_shader_proc);
   say_drawable_set_render_proc(obj->drawable, ray_drawable_render_proc);
   say_drawable_set_index_fill_proc(obj->drawable,
                                    ray_drawable_indices_fill_proc);
@@ -140,6 +168,12 @@ VALUE ray_drawable_init(int argc, VALUE *argv, VALUE self) {
   return self;
 }
 
+void ray_drawable_copy_attr(VALUE self, VALUE orig) {
+  VALUE attr = rb_iv_get(orig, "@shader_attributes");
+  if (!NIL_P(attr))
+    rb_iv_set(self, "@shader_attributes", rb_obj_dup(attr));
+}
+
 static
 VALUE ray_drawable_init_copy(VALUE self, VALUE orig) {
   if (rb_obj_is_kind_of(self, rb_path2class("Ray::Text"))   ||
@@ -157,12 +191,15 @@ VALUE ray_drawable_init_copy(VALUE self, VALUE orig) {
   size_t vid = say_drawable_get_vertex_type(other->drawable);
   obj->drawable = say_drawable_create(vid);
   say_drawable_set_custom_data(obj->drawable, obj);
+  say_drawable_set_other_data(obj->drawable, (void*)self);
   say_drawable_copy(obj->drawable, other->drawable);
   say_drawable_set_changed(obj->drawable);
 
   rb_iv_set(self, "@vertex_type_class", rb_iv_get(orig, "@vertex_type_class"));
   obj->vsize = other->vsize;
 
+  ray_drawable_copy_attr(self, orig);
+
   return self;
 }
 
@@ -261,28 +298,67 @@ VALUE ray_drawable_set_z(VALUE self, VALUE val) {
 }
 
 /*
-  Angle is a rotation applied to a drawable. It is expressed in degrees, in the
-  counter-clockwise direction.
-
-  @return [Float] The rotation applied to the drawable
-*/
+ * Angle is a rotation applied to a drawable. It is expressed in degrees, in the
+ * counter-clockwise direction.
+ *
+ * @return [Float] The rotation applied to the drawable
+ */
 static
 VALUE ray_drawable_angle(VALUE self) {
   return rb_float_new(say_drawable_get_angle(ray_rb2drawable(self)));
 }
 
 /*
-  @overload angle=(val)
-    Sets the rotation applied to the drawable.
-    @see #angle=
-    @param [Float] val The rotation applied to the drawable.
-*/
+ * @overload angle=(val)
+ *   Sets the rotation applied to the drawable.
+ *   @see #angle=
+ *   @param [Float] val The rotation applied to the drawable.
+ */
 static
 VALUE ray_drawable_set_angle(VALUE self, VALUE val) {
   say_drawable_set_angle(ray_rb2drawable(self), NUM2DBL(val));
   return val;
 }
 
+/*
+ * @return [Proc, nil] Proc used to generate matrices, if any.
+ */
+static
+VALUE ray_drawable_matrix_proc(VALUE self) {
+  return rb_iv_get(self, "@matrix_proc");
+}
+
+/*
+ * @overload matrix_proc=(val)
+ *   Sets the proc used to generate matrices. When set to nil, disables
+ *   custom proc. The proc is called with the drawable to generate a matrix
+ *   for, and should return that matrix.
+ *
+ *   @param [Proc, nil] val
+ */
+static
+VALUE ray_drawable_set_matrix_proc(VALUE self, VALUE val) {
+  say_drawable *drawable = ray_rb2drawable(self);
+
+  if (NIL_P(val))
+    say_drawable_set_matrix_proc(drawable, NULL);
+  else
+    say_drawable_set_matrix_proc(drawable, ray_drawable_actual_matrix_proc);
+
+  rb_iv_set(self, "@matrix_proc", val);
+  return val;
+}
+
+/*
+ * Marks the drawable's matrix as changed. This is meant to be called when you
+ * want your matrix proc to be called the next time the matrix is accessed.
+ */
+static
+VALUE ray_drawable_matrix_changed(VALUE self) {
+  say_drawable_set_matrix_changed(ray_rb2drawable(self));
+  return self;
+}
+
 /*
   @return [Ray::Matrix] The transformation matrix used by this object.
 */
@@ -292,15 +368,15 @@ VALUE ray_drawable_matrix(VALUE self) {
 }
 
 /*
-  @overload matrix=(val)
-    Sets the current matrix to a custom one, making Ray ignore attributes
-    setting that change the transformation matrix.
-
-    Setting this to nil will cause Ray to start using the actual transformation
-    matrix.
-
-    @param [Ray::Matrix, nil] val
-*/
+ *  @overload matrix=(val)
+ *    Sets the current matrix to a custom one, making Ray ignore attributes
+ *    setting that change the transformation matrix.
+ *
+ *    Setting this to nil will cause Ray to start using the actual
+ *    transformation matrix.
+ *
+ *    @param [Ray::Matrix, nil] val
+ */
 static
 VALUE ray_drawable_set_matrix(VALUE self, VALUE val) {
   say_drawable *drawable = ray_rb2drawable(self);
@@ -314,12 +390,12 @@ VALUE ray_drawable_set_matrix(VALUE self, VALUE val) {
 }
 
 /*
-  @overload transform(point)
-    Applies the transformations to a point.
-
-    @param [Ray::Vector3] point Point to transform.
-    @return [Ray::Vector3] Transformed point
-*/
+ *  @overload transform(point)
+ *    Applies the transformations to a point
+ *
+ *    @param [Ray::Vector3] point Point to transform.
+ *    @return [Ray::Vector3] Transformed point
+ */
 static
 VALUE ray_drawable_transform(VALUE self, VALUE point) {
   say_vector3 res = say_drawable_transform(ray_rb2drawable(self),
@@ -402,12 +478,81 @@ VALUE ray_drawable_set_textured(VALUE self, VALUE val) {
   return self;
 }
 
+/*
+ * @overload blend_mode=(mode)
+ *   Sets blend mode
+ *
+ *   Ray supports 3 differents blend mode: :add, :multiply, and :alpha (also the
+ *   default). Blending can also be disabled using :none.
+ *
+ *   @param [Symbol] mode New blend mode
+ */
+static
+VALUE ray_drawable_set_blend_mode(VALUE self, VALUE mode) {
+  say_blend_mode c_mode = SAY_BLEND_NO;
+  if (mode == RAY_SYM("alpha"))
+    c_mode = SAY_BLEND_ALPHA;
+  else if (mode == RAY_SYM("add"))
+    c_mode = SAY_BLEND_ADD;
+  else if (mode == RAY_SYM("multiply"))
+    c_mode = SAY_BLEND_MULTIPLY;
+
+  say_drawable_set_blend_mode(ray_rb2drawable(self), c_mode);
+  return mode;
+}
+
+/* @see blend_mode= */
+static
+VALUE ray_drawable_blend_mode(VALUE self) {
+  say_blend_mode mode = say_drawable_get_blend_mode(ray_rb2drawable(self));
+
+  switch (mode) {
+  case SAY_BLEND_NO: return RAY_SYM("none");
+  case SAY_BLEND_ALPHA: return RAY_SYM("alpha");
+  case SAY_BLEND_ADD: return RAY_SYM("add");
+  case SAY_BLEND_MULTIPLY: return RAY_SYM("multiply");
+  }
+
+  return Qnil; /* should never happen */
+}
+
+/*
+ * Document-class: Ray::Drawable
+ *
+ * A drawable object represents anything that can be rendered on a target. This
+ * class allows to define transformations for any drawable and to set states to
+ * create your own drawable.
+ *
+ * A subclass of Ray::Drawable must implement ``render`` to draw the object,
+ * using OpenGL calls:
+ *
+ *    # vertex_id is the index of the first vertex of this object; index_id is
+ *    # the index of the first index of this object in the element buffer. One
+ *    # of those variables at least will be ignored in the implementation
+ *    def render(vertex_id, index_id)
+ *      # do work
+ *    end
+ *
+ * Also, it will often use Ray's system to store vertices and sometimes indices:
+ *
+ *     def fill_vertices
+ *       # returns an array of vertices
+ *     end
+ *
+ * Same with indices:
+ *
+ *     def fill_indices(vertex_id)
+ *       # returns a Ray::GL::IntArray
+ *     end
+ *
+ */
 void Init_ray_drawable() {
   ray_cDrawable = rb_define_class_under(ray_mRay, "Drawable", rb_cObject);
   rb_define_alloc_func(ray_cDrawable, ray_drawable_alloc);
   rb_define_method(ray_cDrawable, "initialize", ray_drawable_init, -1);
   rb_define_method(ray_cDrawable, "initialize_copy", ray_drawable_init_copy, 1);
 
+  /* @group Transformations */
   rb_define_method(ray_cDrawable, "origin", ray_drawable_origin, 0);
   rb_define_method(ray_cDrawable, "origin=", ray_drawable_set_origin, 1);
 
@@ -423,10 +568,19 @@ void Init_ray_drawable() {
   rb_define_method(ray_cDrawable, "angle", ray_drawable_angle, 0);
   rb_define_method(ray_cDrawable, "angle=", ray_drawable_set_angle, 1);
 
+  rb_define_method(ray_cDrawable, "matrix_proc", ray_drawable_matrix_proc, 0);
+  rb_define_method(ray_cDrawable, "matrix_proc=", ray_drawable_set_matrix_proc,
+                   1);
+
+  rb_define_method(ray_cDrawable, "matrix_changed!",
+                   ray_drawable_matrix_changed, 0);
+
   rb_define_method(ray_cDrawable, "matrix", ray_drawable_matrix, 0);
   rb_define_method(ray_cDrawable, "matrix=", ray_drawable_set_matrix, 1);
   rb_define_method(ray_cDrawable, "transform", ray_drawable_transform, 1);
+  /* @endgroup */
 
+  /* @group Rendering options */
   rb_define_method(ray_cDrawable, "shader", ray_drawable_shader, 0);
   rb_define_method(ray_cDrawable, "shader=", ray_drawable_set_shader, 1);
 
@@ -443,4 +597,9 @@ void Init_ray_drawable() {
 
   rb_define_method(ray_cDrawable, "textured=", ray_drawable_set_textured, 1);
   rb_define_method(ray_cDrawable, "textured?", ray_drawable_is_textured, 0);
+
+  rb_define_method(ray_cDrawable, "blend_mode=", ray_drawable_set_blend_mode,
+                   1);
+  rb_define_method(ray_cDrawable, "blend_mode", ray_drawable_blend_mode, 0);
+  /* @endgroup */
 }