ray 0.1.1 → 0.2.0

data/ext/image.c

@@ -21,19 +21,24 @@ VALUE ray_image_alloc(VALUE self) {
 }
 
 /*
-  @overload initialize(io)
-    @param [IO, #read] io An object containing the image.
-    @example
-      open("test.png") { |io| Ray::Image.new(io) }
-  @overload initialize(filename)
-    @param [String] filename Name of a file to load the image from.
-    @example
-      Ray::Image.new "test.png"
-  @overload initialize(size)
-    @param [Vector2, #to_vector2] size Size of the image to create
-    @example
-      Ray::Image.new [64, 128]
-*/
+ * @overload initialize(io)
+ *   Creates an image from an IO object
+ *   @param [IO, #read] io An object containing the image.
+ *   @example
+ *     open("test.png") { |io| Ray::Image.new(io) }
+ *
+ * @overload initialize(filename)
+ *   Loads an image from a file
+ *   @param [String] filename Name of a file to load the image from.
+ *   @example
+ *     Ray::Image.new "test.png"
+ *
+ * @overload initialize(size)
+ *   Creates an image from a size
+ *   @param [Vector2, #to_vector2] size Size of the image to create
+ *   @example
+ *     Ray::Image.new [64, 128]
+ */
 static
 VALUE ray_image_init(VALUE self, VALUE arg) {
   say_image *img = ray_rb2image(self);
@@ -63,16 +68,20 @@ static
 VALUE ray_image_init_copy(VALUE self, VALUE other) {
   say_image *orig = ray_rb2image(other);
 
-  say_image_load_raw(ray_rb2image(self),
-                     say_image_get_width(orig), say_image_get_height(orig),
-                     say_image_get_buffer(orig));
+  say_image_load_flipped_raw(ray_rb2image(self),
+                             say_image_get_width(orig),
+                             say_image_get_height(orig),
+                             say_image_get_buffer(orig));
 
   return self;
 }
 
 /*
  * @overload write_bmp(filename)
- *   Saves the image as a BMP.
+ *   Saves the image as a BMP
+ *
+ *   Notice BMP output ignores alpha channel. Use PNG or TGA output when
+ *   possible.
  */
 static
 VALUE ray_image_write_bmp(VALUE self, VALUE filename) {
@@ -85,7 +94,8 @@ VALUE ray_image_write_bmp(VALUE self, VALUE filename) {
 
 /*
  * @overload write_png(filename)
- *   Saves the image as a PNG.
+ *   Saves the image as a PNG
+ *   @raise [RuntimeError] This method will not work on Windows.
  */
 static
 VALUE ray_image_write_png(VALUE self, VALUE filename) {
@@ -98,7 +108,7 @@ VALUE ray_image_write_png(VALUE self, VALUE filename) {
 
 /*
  * @overload write_tga(filename)
- *   Saves the image as a TGA.
+ *   Saves the image as a TGA
  */
 static
 VALUE ray_image_write_tga(VALUE self, VALUE filename) {
@@ -111,8 +121,11 @@ VALUE ray_image_write_tga(VALUE self, VALUE filename) {
 
 /*
  * @overload write(filename)
- *   Saves the image, tyring to guess the format. If it cannot be guessed, BMP
- *   will be used.
+ *   Saves the image in any format supported by Ray
+ *
+ *   This will try to guess the format based on the filename extension
+ *   (regardless of the case). If Ray can't guess the filename, the image will
+ *   be saved anyway using TGA.
  */
 static
 VALUE ray_image_write(VALUE self, VALUE filename) {
@@ -154,12 +167,14 @@ void ray_image_assert_pos(say_image *img, size_t x, size_t y) {
 }
 
 /*
-  @overload [](x, y)
-    @param [Integer] x X position of the pixel
-    @param [Integer] y Y position of the pixel
-
-    @return [Color] Color of the pixel
-*/
+ * @overload [](x, y)
+ *   Reads the color of a pixel
+ *
+ *   @param [Integer] x X position of the pixel
+ *   @param [Integer] y Y position of the pixel
+ *
+ *   @return [Color] Color of the pixel
+ */
 static
 VALUE ray_image_get(VALUE self, VALUE rb_x, VALUE rb_y) {
   say_image *img = ray_rb2image(self);
@@ -173,12 +188,14 @@ VALUE ray_image_get(VALUE self, VALUE rb_x, VALUE rb_y) {
 }
 
 /*
-  @overload []=(x, y, color)
-    @param [Integer] x X position of the pixel
-    @param [Integer] y Y position of the pixel
-
-    @param [Color] color New color of the pixel
-*/
+ * @overload []=(x, y, color)
+ *   Changes the color of a pixel
+ *
+ *   @param [Integer] x X position of the pixel
+ *   @param [Integer] y Y position of the pixel
+ *
+ *   @param [Color] color New color of the pixel
+ */
 static
 VALUE ray_image_set(VALUE self, VALUE rb_x, VALUE rb_y, VALUE color) {
   rb_check_frozen(self);
@@ -193,36 +210,59 @@ VALUE ray_image_set(VALUE self, VALUE rb_x, VALUE rb_y, VALUE color) {
 }
 
 /*
-  @overload tex_rect(rect)
-    Converts a rect of pixel coordinates to a rect of texture coordinates,
-    which may be needed to generate vertices using this image.
-
-    @param [Rect] rect Rect in pixel coordinates
-    @return [Rect] Rect in texture coordinates
-*/
+ * @overload tex_rect(rect)
+ *   Converts a rect of pixel coordinates to a rect of texture coordinates
+ *
+ *   Texture coordinates can be useful when manually generating vertices that
+ *   need to be textured.
+ *
+ *   The returned rect is setup so that (x,y) is the top left corner of the
+ *   image. The height of the rect may thus be negative.
+ *
+ *   @param [Rect] rect Rect in pixel coordinates
+ *   @return [Rect] Rect in texture coordinates
+ */
 VALUE ray_image_tex_rect(VALUE self, VALUE rect) {
   return ray_rect2rb(say_image_get_tex_rect(ray_rb2image(self),
                                             ray_convert_to_rect(rect)));
 }
 
 /*
-  Binds the texture, which will be used as GL_TEXTURE_2D when drawing with
-  OpenGL
-*/
+ * Binds the texture, which will be used as GL_TEXTURE_2D when drawing with
+ * OpenGL
+ */
 VALUE ray_image_bind(VALUE self) {
   say_image_bind(ray_rb2image(self));
   return self;
 }
 
 /*
-  @return [true, false] True if the image uses linear interplation when it's
-    drawn with a different size than the normal one. Uses the color of the
-    nearest pixel otherwise.
+ * @return [Integer] Identifer of the image's texture
+ */
+VALUE ray_image_texture(VALUE self) {
+  return ULONG2NUM(say_image_get_texture(ray_rb2image(self)));
+}
+
+/*
+ * @see smooth=
  */
 VALUE ray_image_is_smooth(VALUE self) {
   return say_image_is_smooth(ray_rb2image(self)) ? Qtrue : Qfalse;
 }
 
+/*
+ * @overload smooth=(val)
+ *   Enables or disables smoothing
+ *
+ *   When smoothing is enabled, the color of interpolated pixels is chosen by
+ *   taking the average of the four colors that are the nearest to each of
+ *   them (linear interpolation). When it is not enabled, the color of the
+ *   nearest point is simply used.
+ *
+ *   Smoothing is disabled by default.
+ *
+ *   @param [Boolean] val True to enable smoothing
+ */
 VALUE ray_image_set_smooth(VALUE self, VALUE val) {
   rb_check_frozen(self);
   say_image_set_smooth(ray_rb2image(self), RTEST(val));
@@ -230,34 +270,58 @@ VALUE ray_image_set_smooth(VALUE self, VALUE val) {
 }
 
 /*
-  Document-class: Ray::Image
-
-  An image is only the resource used when drawing. It is not the object you can
-  directly draw on the screen.
-*/
+ * Document-class: Ray::Image
+ *
+ * An image is a bidimensonial array of pixels used to texture rendering. It is
+ * not an object you can draw per se. See {Ray::Sprite} or more generically
+ * {Ray::Drawable} for this.
+ *
+ * You can directly access pixels of an image, but an image target
+ * ({Ray::ImageTarget}) must be used to be able to draw more complex objects
+ * on it.
+ *
+ * @see Ray::ImageTarget
+ * @see Ray::Sprite
+ * @see Ray::Drawable
+ */
 void Init_ray_image() {
   ray_cImage = rb_define_class_under(ray_mRay, "Image", rb_cObject);
 
+  /* @group Creating an image */
   rb_define_alloc_func(ray_cImage, ray_image_alloc);
   rb_define_method(ray_cImage, "initialize", ray_image_init, 1);
   rb_define_method(ray_cImage, "initialize_copy", ray_image_init_copy, 1);
+  /* @endgroup */
 
+  /* @group Saving an image */
   rb_define_method(ray_cImage, "write_bmp", ray_image_write_bmp, 1);
   rb_define_method(ray_cImage, "write_png", ray_image_write_png, 1);
   rb_define_method(ray_cImage, "write_tga", ray_image_write_tga, 1);
   rb_define_method(ray_cImage, "write", ray_image_write, 1);
+  /* @endgroup */
 
+  /* @group Getting image size */
   rb_define_method(ray_cImage, "width", ray_image_width, 0);
   rb_define_method(ray_cImage, "height", ray_image_height, 0);
   rb_define_method(ray_cImage, "size", ray_image_size, 0);
+  /* @endgroup */
 
+  /* @group Pixel-level access */
   rb_define_method(ray_cImage, "[]", ray_image_get, 2);
   rb_define_method(ray_cImage, "[]=", ray_image_set, 3);
+  /* @endgroup */
 
+  /* @group Texture parameters */
   rb_define_method(ray_cImage, "smooth?", ray_image_is_smooth, 0);
   rb_define_method(ray_cImage, "smooth=", ray_image_set_smooth, 1);
+  /* @endgroup */
 
+  /* @group Coordinate conversions */
   rb_define_method(ray_cImage, "tex_rect", ray_image_tex_rect, 1);
+  /* @endgroup */
 
+  /* @group OpenGL access */
   rb_define_method(ray_cImage, "bind", ray_image_bind, 0);
+  rb_define_method(ray_cImage, "texture", ray_image_texture, 0);
+  /* @endgroup */
 }

data/ext/image_target.c

@@ -17,13 +17,17 @@ say_image_target *ray_rb2image_target(VALUE obj) {
 VALUE ray_image_target_alloc(VALUE self) {
   if (!say_image_target_is_available())
     rb_raise(rb_eRuntimeError, "Ray::RenderImage is not supported here");
-  
+
   say_image_target *target = say_image_target_create();
   return Data_Wrap_Struct(ray_cImageTarget, NULL, say_image_target_free,
                           target);
 }
 
-/* @overload image=(img) */
+/*
+ * @overload image=(img)
+ *   Sets the image this object will draw on
+ *   @param [Ray::Image] img New image to draw on
+ */
 VALUE ray_image_target_set_image(VALUE self, VALUE img) {
   rb_check_frozen(self);
   say_image_target_set_image(ray_rb2image_target(self), ray_rb2image(img));
@@ -31,26 +35,50 @@ VALUE ray_image_target_set_image(VALUE self, VALUE img) {
   return img;
 }
 
-/* @return [Ray::Image] image the target draws on */
+/* @see image= */
 VALUE ray_image_target_image(VALUE self) {
   return rb_iv_get(self, "@image");
 }
 
-/* Updates the content of the image target */
+/*
+ * Updates the content of the image target
+ *
+ * The pixels of the image will also be updated:
+ *    Ray::ImageTarget.new image do |target|
+ *      target.clear Ray::Color.red
+ *      target.update
+ *    end
+ *
+ *    image[0, 0] # => RGBA(255, 0, 0, 255)
+ */
 VALUE ray_image_target_update(VALUE self) {
   say_image_target_update(ray_rb2image_target(self));
   return self;
 }
 
-/* Binds an image target to draw directly on it */
+/*
+ * Binds an image target to draw directly on it
+ *
+ * This method is only useful when performing low-level OpenGL rendering. It
+ * is different from {#make_current} because it doesn't use the target's own
+ * OpenGL context. Instead, it will use the current context (ensuring there is
+ * one).
+ *
+ * Notice binding the image target (and, therefore, making it the current
+ * target) clears the depth buffer of the image, so that everything will be
+ * rendered over what was already on the image.
+ */
 VALUE ray_image_target_bind(VALUE self) {
   say_image_target_bind(ray_rb2image_target(self));
   return self;
 }
 
 /*
- * Unbinds any image target. This is mostly not needed, as making a window the
- * current target will call this automatically.
+ * Unbinds any image target
+ *
+ * This is rarely needed, as this method gets called automatically when a window
+ * is bound, and because windows and image targets do not share the same OpenGL
+ * context.
  */
 VALUE ray_image_target_unbind(VALUE self) {
   /*
@@ -63,18 +91,38 @@ VALUE ray_image_target_unbind(VALUE self) {
 }
 
 /*
+ * Checks availability of image targets
+ *
+ * Image targets are only part of OpenGL core since OpenGL 3 (although they may
+ * be supported as an extension in older versions).
+ *
  * @return [true, false] True when ImageTargets are available
  */
 VALUE ray_image_target_available(VALUE self) {
   return say_image_target_is_available() ? Qtrue : Qfalse;
 }
 
+/*
+ * Document-class: Ray::ImageTarget
+ *
+ * Image targets are objects that allow to draw any drawable object on an image
+ * instead of doing on-screen rendering. Off-screen rendering can be useful to
+ * pre-render some objects.
+ *
+ * Notice image targets modify the image they are drawing on directly. You may
+ * therefore not want to draw on a cached image, but rather on a copy thereof.
+ *
+ * @see Ray::Image
+ */
 void Init_ray_image_target() {
-  ray_cImageTarget = rb_define_class_under(ray_mRay, "ImageTarget", ray_cTarget);
+  ray_cImageTarget = rb_define_class_under(ray_mRay, "ImageTarget",
+                                           ray_cTarget);
   rb_define_alloc_func(ray_cImageTarget, ray_image_target_alloc);
 
-  rb_define_singleton_method(ray_cImageTarget, "unbind", ray_image_target_unbind, 0);
-  rb_define_singleton_method(ray_cImageTarget, "available?", ray_image_target_available, 0);
+  rb_define_singleton_method(ray_cImageTarget, "unbind",
+                             ray_image_target_unbind, 0);
+  rb_define_singleton_method(ray_cImageTarget, "available?",
+                             ray_image_target_available, 0);
 
   rb_define_method(ray_cImageTarget, "image=", ray_image_target_set_image, 1);
   rb_define_method(ray_cImageTarget, "image", ray_image_target_image, 0);

data/ext/input.c

@@ -17,21 +17,72 @@ say_input *ray_rb2input(VALUE obj) {
 VALUE ray_input2rb(say_input *input, VALUE owner) {
   VALUE obj = Data_Wrap_Struct(rb_path2class("Ray::Input"), NULL, NULL, input);
   rb_iv_set(obj, "@owner", owner);
-
   return obj;
 }
 
 static
 VALUE ray_input_alloc(VALUE self) {
-  rb_raise(rb_eRuntimeError, "can't allocate Ray::Input");
+  say_input *obj = malloc(sizeof(say_input));
+  say_input_reset(obj);
+  return Data_Wrap_Struct(self, NULL, free, obj);
+}
+
+/*
+ * Resets the input
+ *
+ * After a reset, all the keys are marked released and the mouse position is set
+ * to (0, 0).
+ */
+static
+VALUE ray_input_reset(VALUE self) {
+  say_input_reset(ray_rb2input(self));
+  return self;
+}
+
+/*
+ * @overload press(key)
+ *   Marks a key as pressed
+ *   @param [Integer] key A key
+ */
+static
+VALUE ray_input_press(VALUE self, VALUE key) {
+  say_input_press(ray_rb2input(self), NUM2INT(key));
+  return Qnil;
+}
+
+/*
+ * @overload release(key)
+ *   Marks a key as released
+ *   @param [Integer] key A key
+ */
+static
+VALUE ray_input_release(VALUE self, VALUE key) {
+  say_input_release(ray_rb2input(self), NUM2INT(key));
   return Qnil;
 }
 
 /*
-  @overload holding?(key)
-    @param [Integer] key A key
-    @return [true, false] True if the given key is being held
-*/
+ * @overload mouse_pos=(pos)
+ *   Changes the known position of the mouse
+ *
+ *   Notice this only affects the input object's state, it won't actually move
+ *   the mouse.
+ *
+ *   @param [Ray::Vector2] pos New position
+ */
+static
+VALUE ray_input_set_mouse_pos(VALUE self, VALUE pos) {
+  say_input_set_mouse_pos(ray_rb2input(self), ray_convert_to_vector2(pos));
+  return pos;
+}
+
+/*
+ * @overload holding?(key)
+ *   Checks if a key is being held
+ *
+ *   @param [Integer] key A key
+ *   @return [true, false] True if the given key is being held
+ */
 static
 VALUE ray_input_holding(VALUE self, VALUE key) {
   return say_input_is_holding(ray_rb2input(self), NUM2INT(key)) ?
@@ -44,10 +95,26 @@ VALUE ray_input_mouse_pos(VALUE self) {
   return ray_vector2_to_rb(say_input_get_mouse_pos(ray_rb2input(self)));
 }
 
+/*
+ * Document-class: Ray::Input
+ *
+ * An input object is used to keep track of pressed keys and the position of the
+ * mouse. Methods are also provided to affect the state of the input, possibly
+ * useful in tests.
+ */
 void Init_ray_input() {
   ray_cInput = rb_define_class_under(ray_mRay, "Input", rb_cObject);
   rb_define_alloc_func(ray_cInput, ray_input_alloc);
 
+  /* @group Change input */
+  rb_define_method(ray_cInput, "reset", ray_input_reset, 0);
+  rb_define_method(ray_cInput, "press", ray_input_press, 1);
+  rb_define_method(ray_cInput, "release", ray_input_release, 1);
+  rb_define_method(ray_cInput, "mouse_pos=", ray_input_set_mouse_pos, 1);
+  /* @engroup */
+
+  /* @group Read input */
   rb_define_method(ray_cInput, "holding?", ray_input_holding, 1);
   rb_define_method(ray_cInput, "mouse_pos", ray_input_mouse_pos, 0);
+  /* @endgroup */
 }