sfml3-rb 0.2.2 → 0.3.1

data/ext/graphics/transform.c

@@ -62,9 +62,18 @@ static VALUE Transform_alloc(VALUE klass) {
     return TypedData_Wrap_Struct(klass, &Transform_data_type, transform);
 }
 
-/* new                    -> identity
-   new(array_of_9)        -> from that matrix
-   new(a00, a01, ... a22) -> from those nine elements */
+/* call-seq:
+ *   Transform.new                    -> identity Transform
+ *   Transform.new(array_of_9)        -> Transform
+ *   Transform.new(a00, a01, ... a22) -> Transform
+ *
+ * A Transform wraps a 3x3 matrix (9 floats, row-major). With no arguments it
+ * is the identity transform; with a single 9-element Array or nine
+ * individual numbers, it is built from those matrix elements directly.
+ *
+ * @return [Transform]
+ * @raise [ArgumentError] if given an argument count other than 0, 1 or 9
+ */
 static VALUE Transform_init(int argc, VALUE* argv, VALUE self) {
     sfTransform* transform = Get_Transform_Struct(self);
     float matrix[MATRIX_LENGTH];
@@ -93,11 +102,26 @@ static VALUE Transform_init(int argc, VALUE* argv, VALUE self) {
     return self;
 }
 
+/* call-seq:
+ *   Transform.identity -> Transform
+ *
+ * Returns the identity transform.
+ *
+ * @return [Transform] a fresh identity transform
+ */
 static VALUE Transform_s_identity(VALUE klass) {
     (void)klass;
     return Transform_wrap(sfTransform_Identity);
 }
 
+/* call-seq:
+ *   Transform.from_a(array_of_9) -> Transform
+ *
+ * Creates a transform from a nine-element array.
+ *
+ * @return [Transform]
+ * @raise [ArgumentError] if the Array has fewer than 9 elements
+ */
 static VALUE Transform_s_from_a(VALUE klass, VALUE rb_matrix) {
     (void)klass;
     return Transform_wrap(Transform_ArrayToTransform(rb_matrix));
@@ -107,6 +131,12 @@ static VALUE Transform_s_from_a(VALUE klass, VALUE rb_matrix) {
 /* Matrix access                                                              */
 /* -------------------------------------------------------------------------- */
 
+/* call-seq: to_a -> Array<Float>
+ *
+ * Returns the object as an Array.
+ *
+ * @return [Array<Float>] the 9 matrix elements, row-major
+ */
 static VALUE Transform_to_a(VALUE self) {
     return Transform_MatrixToArray(Get_Transform_Struct(self)->matrix);
 }
@@ -114,6 +144,13 @@ static VALUE Transform_to_a(VALUE self) {
 /* The 16-float 4x4 that sfTransform_getMatrix() fills, ready for glLoadMatrixf.
    Deliberately not called #matrix: that name already means the 3x3 everywhere
    else in this binding (Sprite#matrix, Text#matrix, RenderState#matrix). */
+/* call-seq: gl_matrix -> Array<Float>
+ *
+ * Returns the transform as a 4x4 OpenGL matrix.
+ *
+ * @return [Array<Float>] the equivalent 16-element 4x4 matrix, ready for
+ *   +glLoadMatrixf+
+ */
 static VALUE Transform_gl_matrix(VALUE self) {
     float matrix[GL_MATRIX_LENGTH];
     VALUE rb_arr;
@@ -130,6 +167,13 @@ static VALUE Transform_gl_matrix(VALUE self) {
     return rb_arr;
 }
 
+/* call-seq:
+ *   self == other -> true or false
+ *
+ * +other+ may be a Transform or a 9-element Array.
+ *
+ * @return [Boolean]
+ */
 static VALUE Transform_eql(VALUE self, VALUE rb_other) {
     sfTransform other;
 
@@ -142,6 +186,12 @@ static VALUE Transform_eql(VALUE self, VALUE rb_other) {
     return BOOL2RB(sfTransform_equal(Get_Transform_Struct(self), &other));
 }
 
+/* call-seq: to_s -> String
+ *
+ * Returns a human-readable representation of the object.
+ *
+ * @return [String]
+ */
 static VALUE Transform_to_s(VALUE self) {
     const float* m = Get_Transform_Struct(self)->matrix;
 
@@ -153,6 +203,13 @@ static VALUE Transform_to_s(VALUE self) {
 /* Application                                                                */
 /* -------------------------------------------------------------------------- */
 
+/* call-seq:
+ *   transform_point(point) -> Vector2
+ *
+ * Applies the transform to a point and returns the result.
+ *
+ * @return [Vector2] +point+ transformed by this matrix
+ */
 static VALUE Transform_transform_point(VALUE self, VALUE rb_point) {
     sfVector2f point =
         sfTransform_transformPoint(Get_Transform_Struct(self), vec2f_from_rb(rb_point));
@@ -160,16 +217,37 @@ static VALUE Transform_transform_point(VALUE self, VALUE rb_point) {
     return vec2f_to_rb(point);
 }
 
+/* call-seq:
+ *   transform_rect(rect) -> Rect
+ *
+ * Applies the transform to a rectangle and returns the result.
+ *
+ * @return [Rect] the axis-aligned bounding box of +rect+ transformed by
+ *   this matrix
+ */
 static VALUE Transform_transform_rect(VALUE self, VALUE rb_rect) {
     sfFloatRect rect = sfTransform_transformRect(Get_Transform_Struct(self), rect_from_rb(rb_rect));
 
     return rect_to_rb(rect);
 }
 
+/* call-seq: inverse -> Transform
+ *
+ * Returns the inverse of the transform.
+ *
+ * @return [Transform] the inverse of this transform, or the identity if it
+ *   is not invertible
+ */
 static VALUE Transform_get_inverse(VALUE self) {
     return Transform_wrap(sfTransform_getInverse(Get_Transform_Struct(self)));
 }
 
+/* call-seq: copy -> Transform
+ *
+ * Returns a deep copy of the object.
+ *
+ * @return [Transform] an independent copy
+ */
 static VALUE Transform_copy(VALUE self) {
     return Transform_wrap(*Get_Transform_Struct(self));
 }
@@ -178,6 +256,14 @@ static VALUE Transform_copy(VALUE self) {
 /* Mutators -- each returns self so they chain                                */
 /* -------------------------------------------------------------------------- */
 
+/* call-seq:
+ *   combine!(other) -> self
+ *
+ * Combines this transform with +other+ (a Transform or 9-element Array) in
+ * place, equivalent to matrix multiplication (+self+ * +other+).
+ *
+ * @return [self]
+ */
 static VALUE Transform_combine_bang(VALUE self, VALUE rb_other) {
     sfTransform other = Transform_ArrayToTransform(rb_other);
 
@@ -186,6 +272,16 @@ static VALUE Transform_combine_bang(VALUE self, VALUE rb_other) {
     return self;
 }
 
+/* call-seq:
+ *   self * other -> Transform
+ *   combine(other) -> Transform
+ *
+ * Non-mutating combination: returns a new Transform equal to +self+
+ * combined with +other+ (a Transform or 9-element Array), leaving both
+ * operands untouched.
+ *
+ * @return [Transform]
+ */
 static VALUE Transform_mul(VALUE self, VALUE rb_other) {
     sfTransform combined = *Get_Transform_Struct(self);
     sfTransform other = Transform_ArrayToTransform(rb_other);
@@ -195,11 +291,27 @@ static VALUE Transform_mul(VALUE self, VALUE rb_other) {
     return Transform_wrap(combined);
 }
 
+/* call-seq:
+ *   translate!(offset) -> self
+ *
+ * Applies a translation to the transform in place.
+ *
+ * @return [self]
+ */
 static VALUE Transform_translate_bang(VALUE self, VALUE rb_offset) {
     sfTransform_translate(Transform_writable(self), vec2f_from_rb(rb_offset));
     return self;
 }
 
+/* call-seq:
+ *   rotate!(angle)         -> self
+ *   rotate!(angle, center) -> self
+ *
+ * Rotates by +angle+ degrees in place, around +center+ if given, otherwise
+ * around the origin.
+ *
+ * @return [self]
+ */
 static VALUE Transform_rotate_bang(int argc, VALUE* argv, VALUE self) {
     VALUE rb_angle, rb_center;
     sfTransform* transform;
@@ -216,6 +328,15 @@ static VALUE Transform_rotate_bang(int argc, VALUE* argv, VALUE self) {
     return self;
 }
 
+/* call-seq:
+ *   scale!(factors)         -> self
+ *   scale!(factors, center) -> self
+ *
+ * Scales by +factors+ (a Vector2 or 2-element Array) in place, around
+ * +center+ if given, otherwise around the origin.
+ *
+ * @return [self]
+ */
 static VALUE Transform_scale_bang(int argc, VALUE* argv, VALUE self) {
     VALUE rb_factors, rb_center;
     sfTransform* transform;
@@ -233,14 +354,39 @@ static VALUE Transform_scale_bang(int argc, VALUE* argv, VALUE self) {
 }
 
 /* Non-mutating forms: copy, then apply. */
+/* call-seq:
+ *   translate(offset) -> Transform
+ *
+ * Returns a copy translated by the given offsets.
+ *
+ * @return [Transform] a new transform, translated by +offset+
+ */
 static VALUE Transform_translate(VALUE self, VALUE rb_offset) {
     return Transform_translate_bang(Transform_copy(self), rb_offset);
 }
 
+/* call-seq:
+ *   rotate(angle)         -> Transform
+ *   rotate(angle, center) -> Transform
+ *
+ * Returns a copy rotated by +angle+ degrees, around +center+ if given.
+ *
+ * @return [Transform] a new transform, rotated by +angle+ degrees around
+ *   +center+ if given, otherwise around the origin
+ */
 static VALUE Transform_rotate(int argc, VALUE* argv, VALUE self) {
     return Transform_rotate_bang(argc, argv, Transform_copy(self));
 }
 
+/* call-seq:
+ *   scale(factors)         -> Transform
+ *   scale(factors, center) -> Transform
+ *
+ * Returns a copy scaled by +factors+, around +center+ if given.
+ *
+ * @return [Transform] a new transform, scaled by +factors+ around +center+
+ *   if given, otherwise around the origin
+ */
 static VALUE Transform_scale(int argc, VALUE* argv, VALUE self) {
     return Transform_scale_bang(argc, argv, Transform_copy(self));
 }
@@ -252,6 +398,15 @@ static VALUE Transform_scale(int argc, VALUE* argv, VALUE self) {
 /* Transform used to be a module whose two functions took and returned plain
    9-element Arrays. Both are kept, Array-in/Array-out, so existing callers are
    unaffected by the promotion to a class. */
+/* call-seq:
+ *   Transform.combine(array_a, array_b) -> Array<Float>
+ *
+ * Returns the transform that combines +array_a+ and +array_b+.
+ *
+ * @deprecated Use #combine on a Transform instead.
+ * @return [Array<Float>] the 9-element matrix of +array_a+ combined with
+ *   +array_b+
+ */
 static VALUE Transform_s_combine(VALUE klass, VALUE rb_arr_a, VALUE rb_arr_b) {
     sfTransform transform_a = Transform_ArrayToTransform(rb_arr_a);
     sfTransform transform_b = Transform_ArrayToTransform(rb_arr_b);
@@ -263,6 +418,14 @@ static VALUE Transform_s_combine(VALUE klass, VALUE rb_arr_a, VALUE rb_arr_b) {
     return Transform_MatrixToArray(transform_a.matrix);
 }
 
+/* call-seq:
+ *   Transform.inverse(array) -> Array<Float>
+ *
+ * Returns the inverse of the given transform.
+ *
+ * @deprecated Use #inverse on a Transform instead.
+ * @return [Array<Float>] the 9-element inverse matrix of +array+
+ */
 static VALUE Transform_s_inverse(VALUE klass, VALUE rb_matrix) {
     sfTransform transform = Transform_ArrayToTransform(rb_matrix);
 
@@ -271,8 +434,17 @@ static VALUE Transform_s_inverse(VALUE klass, VALUE rb_matrix) {
     return Transform_MatrixToArray(sfTransform_getInverse(&transform).matrix);
 }
 
-void Init_Transform(VALUE rb_module) {
-    rb_cTransform = rb_define_class_under(rb_module, "Transform", rb_cObject);
+/* Document-class: SFML::Transform
+ * A 3x3 matrix describing a 2D transformation (translation, rotation,
+ * scaling, or any combination). Used to build up and query the
+ * transformations applied by Sprite, Text and Transformable.
+ *
+ * @!attribute [r] matrix
+ *   The object's 3x3 transform matrix.
+ *   @return [Array<Float>] the 9 matrix elements, row-major (alias for #to_a)
+ */
+void Init_Transform(VALUE rb_mSFML) {
+    rb_cTransform = rb_define_class_under(rb_mSFML, "Transform", rb_cObject);
 
     rb_define_alloc_func(rb_cTransform, Transform_alloc);
     rb_define_method(rb_cTransform, "initialize", Transform_init, -1);
@@ -305,6 +477,7 @@ void Init_Transform(VALUE rb_module) {
     rb_define_method(rb_cTransform, "scale", Transform_scale, -1);
     rb_define_method(rb_cTransform, "scale!", Transform_scale_bang, -1);
 
+    /* The identity transform, frozen. */
     rb_define_const(rb_cTransform, "IDENTITY", rb_obj_freeze(Transform_wrap(sfTransform_Identity)));
 }
 

data/ext/graphics/transformable.c

@@ -24,22 +24,34 @@ static const rb_data_type_t Transformable_data_type = {
     .function = {.dmark = NULL, .dfree = Transformable_free, .dsize = NULL},
     .flags = RUBY_TYPED_FREE_IMMEDIATELY};
 
-static VALUE Transformable_new(VALUE klass) {
-    VALUE self;
-    sfTransformable* transformable;
+static VALUE Transformable_alloc(VALUE klass) {
+    sfTransformable* transformable = Transformable_create();
 
-    transformable = Transformable_create();
-    self = TypedData_Wrap_Struct(klass, &Transformable_data_type, transformable);
+    if (transformable == NULL) {
+        rb_raise(rb_eRuntimeError, "failed to create transformable");
+    }
 
-    rb_obj_call_init(self, 0, NULL);
-
-    return self;
+    return TypedData_Wrap_Struct(klass, &Transformable_data_type, transformable);
 }
 
+/* call-seq:
+ *   Transformable.new -> Transformable
+ *
+ * Creates a transformable object with a default position, rotation and scale.
+ *
+ * @return [Transformable]
+ */
 static VALUE Transformable_init(VALUE self) {
     return self;
 }
 
+/* call-seq:
+ *   position=(value) -> self
+ *
+ * Sets the object's position.
+ *
+ * @return [self]
+ */
 static VALUE Transformable_set_position(VALUE self, VALUE rb_position) {
     sfVector2f position = VEC2_RB2C(rb_position);
     sfTransformable_setPosition(Get_Transformable_Struct(self), position);
@@ -47,12 +59,26 @@ static VALUE Transformable_set_position(VALUE self, VALUE rb_position) {
     return self;
 }
 
+/* call-seq:
+ *   rotation=(value) -> self
+ *
+ * Sets the object's rotation, in degrees.
+ *
+ * @return [self]
+ */
 static VALUE Transformable_set_rotation(VALUE self, VALUE rb_angle) {
     sfTransformable_setRotation(Get_Transformable_Struct(self), NUM2DBL(rb_angle));
 
     return self;
 }
 
+/* call-seq:
+ *   scale=(value) -> self
+ *
+ * Sets the object's scale factors.
+ *
+ * @return [self]
+ */
 static VALUE Transformable_set_scale(VALUE self, VALUE rb_scale) {
     sfVector2f scale = VEC2_RB2C(rb_scale);
     sfTransformable_setScale(Get_Transformable_Struct(self), scale);
@@ -60,6 +86,13 @@ static VALUE Transformable_set_scale(VALUE self, VALUE rb_scale) {
     return self;
 }
 
+/* call-seq:
+ *   origin=(value) -> self
+ *
+ * Sets the object's origin.
+ *
+ * @return [self]
+ */
 static VALUE Transformable_set_origin(VALUE self, VALUE rb_origin) {
     sfVector2f origin = VEC2_RB2C(rb_origin);
     sfTransformable_setOrigin(Get_Transformable_Struct(self), origin);
@@ -67,28 +100,59 @@ static VALUE Transformable_set_origin(VALUE self, VALUE rb_origin) {
     return self;
 }
 
+/* call-seq: position -> Vector2
+ *
+ * Returns the object's position.
+ *
+ * @return [Vector2]
+ */
 static VALUE Transformable_get_position(VALUE self) {
     sfVector2f position = sfTransformable_getPosition(Get_Transformable_Struct(self));
 
     return VEC2_C2RB(position);
 }
 
+/* call-seq: rotation -> Float
+ *
+ * Returns the object's rotation, in degrees.
+ *
+ * @return [Float] the current rotation, in degrees
+ */
 static VALUE Transformable_get_rotation(VALUE self) {
     return DBL2NUM(sfTransformable_getRotation(Get_Transformable_Struct(self)));
 }
 
+/* call-seq: scale -> Vector2
+ *
+ * Returns the object's scale factors.
+ *
+ * @return [Vector2]
+ */
 static VALUE Transformable_get_scale(VALUE self) {
     sfVector2f scale = sfTransformable_getScale(Get_Transformable_Struct(self));
 
     return VEC2_C2RB(scale);
 }
 
+/* call-seq: origin -> Vector2
+ *
+ * Returns the object's origin.
+ *
+ * @return [Vector2]
+ */
 static VALUE Transformable_get_origin(VALUE self) {
     sfVector2f origin = sfTransformable_getOrigin(Get_Transformable_Struct(self));
 
     return VEC2_C2RB(origin);
 }
 
+/* call-seq:
+ *   move(offset) -> self
+ *
+ * Adds +offset+ to the current position.
+ *
+ * @return [self]
+ */
 static VALUE Transformable_move(VALUE self, VALUE rb_move) {
     sfVector2f move = VEC2_RB2C(rb_move);
     sfTransformable_move(Get_Transformable_Struct(self), move);
@@ -96,12 +160,26 @@ static VALUE Transformable_move(VALUE self, VALUE rb_move) {
     return self;
 }
 
+/* call-seq:
+ *   rotate(angle) -> self
+ *
+ * Adds +angle+ degrees to the current rotation.
+ *
+ * @return [self]
+ */
 static VALUE Transformable_rotate(VALUE self, VALUE rb_angle) {
     sfTransformable_rotate(Get_Transformable_Struct(self), NUM2DBL(rb_angle));
 
     return self;
 }
 
+/* call-seq:
+ *   scale!(factors) -> self
+ *
+ * Multiplies the current scale componentwise by +factors+.
+ *
+ * @return [self]
+ */
 static VALUE Transformable_scale(VALUE self, VALUE rb_scale) {
     sfVector2f scale = VEC2_RB2C(rb_scale);
     sfTransformable_scale(Get_Transformable_Struct(self), scale);
@@ -109,6 +187,13 @@ static VALUE Transformable_scale(VALUE self, VALUE rb_scale) {
     return self;
 }
 
+/* call-seq: transform -> Array<Float>
+ *
+ * Returns the object's 3x3 row-major transform matrix.
+ *
+ * @return [Array<Float>] the 9-element matrix (also available as #matrix)
+ *   combining this object's position, rotation, scale and origin
+ */
 static VALUE Transformable_get_matrix(VALUE self) {
     sfTransformable* transformable = Get_Transformable_Struct(self);
     sfTransform transform = sfTransformable_getTransform(transformable);
@@ -116,12 +201,24 @@ static VALUE Transformable_get_matrix(VALUE self) {
     return Transform_MatrixToArray(transform.matrix);
 }
 
+/* call-seq: inverse_transform -> Array<Float>
+ *
+ * Returns the 3x3 row-major inverse of the object's transform matrix.
+ *
+ * @return [Array<Float>] the inverse of #transform
+ */
 static VALUE Transformable_get_inverse_matrix(VALUE self) {
     sfTransform transform = sfTransformable_getInverseTransform(Get_Transformable_Struct(self));
 
     return Transform_MatrixToArray(transform.matrix);
 }
 
+/* call-seq: copy -> Transformable
+ *
+ * Returns a deep copy of the object.
+ *
+ * @return [Transformable] an independent copy
+ */
 static VALUE Transformable_copy(VALUE self) {
     sfTransformable* copy = sfTransformable_copy(Get_Transformable_Struct(self));
     VALUE other = TypedData_Wrap_Struct(rb_cTransformable, &Transformable_data_type, copy);
@@ -131,10 +228,28 @@ static VALUE Transformable_copy(VALUE self) {
     return other;
 }
 
-void Init_Transformable(VALUE rb_module) {
-    rb_cTransformable = rb_define_class_under(rb_module, "Transformable", rb_cObject);
-
-    rb_define_singleton_method(rb_cTransformable, "new", Transformable_new, 0);
+/* Document-class: SFML::Transformable
+ * A standalone position/rotation/scale/origin, decoupled from any drawable
+ * object -- the same transform state that Sprite, Text and Shape each carry
+ * internally, usable on its own (e.g. as a scene-graph node).
+ *
+ * @!attribute position
+ *   The object's position.
+ *   @return [Vector2]
+ * @!attribute rotation
+ *   The object's rotation, in degrees.
+ *   @return [Float] degrees
+ * @!attribute scale
+ *   The object's scale factors.
+ *   @return [Vector2]
+ * @!attribute origin
+ *   The object's origin.
+ *   @return [Vector2]
+ */
+void Init_Transformable(VALUE rb_mSFML) {
+    rb_cTransformable = rb_define_class_under(rb_mSFML, "Transformable", rb_cObject);
+
+    rb_define_alloc_func(rb_cTransformable, Transformable_alloc);
     rb_define_method(rb_cTransformable, "initialize", Transformable_init, 0);
 
     rb_define_method(rb_cTransformable, "position=", Transformable_set_position, 1);