sfml3-rb 0.2.2 → 0.3.0

data/ext/graphics/blend_mode.c

@@ -13,27 +13,25 @@ typedef struct {
 
 static VALUE rb_cBlendMode;
 
-static const char *factor_names[] = {
-    "zero", "one", "src_color", "one_minus_src_color", "dst_color",
-    "one_minus_dst_color", "src_alpha", "one_minus_src_alpha", "dst_alpha", "one_minus_dst_alpha"
-};
+static const char* factor_names[] = {"zero",      "one",
+                                     "src_color", "one_minus_src_color",
+                                     "dst_color", "one_minus_dst_color",
+                                     "src_alpha", "one_minus_src_alpha",
+                                     "dst_alpha", "one_minus_dst_alpha"};
 
-static const char *equation_names[] = {
-    "add", "subtract", "reverse_subtract", "min", "max"
-};
+static const char* equation_names[] = {"add", "subtract", "reverse_subtract", "min", "max"};
 
-static void BlendMode_free(void *ptr) {
+static void BlendMode_free(void* ptr) {
     free(ptr);
 }
 
 static const rb_data_type_t BlendMode_data_type = {
     .wrap_struct_name = "SFML::BlendMode",
     .function = {.dmark = NULL, .dfree = BlendMode_free, .dsize = NULL},
-    .flags = RUBY_TYPED_FREE_IMMEDIATELY
-};
+    .flags = RUBY_TYPED_FREE_IMMEDIATELY};
 
 static VALUE BlendMode_wrap(sfBlendMode mode) {
-    BlendMode *ptr = malloc(sizeof(BlendMode));
+    BlendMode* ptr = malloc(sizeof(BlendMode));
 
     ptr->mode = mode;
 
@@ -44,15 +42,15 @@ static sfBlendFactor factor_from_rb(VALUE rb_factor) {
     size_t i;
 
     if (RB_INTEGER_TYPE_P(rb_factor)) {
-        return (sfBlendFactor) NUM2INT(rb_factor);
+        return (sfBlendFactor)NUM2INT(rb_factor);
     }
 
     if (SYMBOL_P(rb_factor)) {
-        const char *name = rb_id2name(SYM2ID(rb_factor));
+        const char* name = rb_id2name(SYM2ID(rb_factor));
 
         for (i = 0; i < sizeof(factor_names) / sizeof(factor_names[0]); i++) {
             if (strcmp(name, factor_names[i]) == 0) {
-                return (sfBlendFactor) i;
+                return (sfBlendFactor)i;
             }
         }
     }
@@ -65,15 +63,15 @@ static sfBlendEquation equation_from_rb(VALUE rb_equation) {
     size_t i;
 
     if (RB_INTEGER_TYPE_P(rb_equation)) {
-        return (sfBlendEquation) NUM2INT(rb_equation);
+        return (sfBlendEquation)NUM2INT(rb_equation);
     }
 
     if (SYMBOL_P(rb_equation)) {
-        const char *name = rb_id2name(SYM2ID(rb_equation));
+        const char* name = rb_id2name(SYM2ID(rb_equation));
 
         for (i = 0; i < sizeof(equation_names) / sizeof(equation_names[0]); i++) {
             if (strcmp(name, equation_names[i]) == 0) {
-                return (sfBlendEquation) i;
+                return (sfBlendEquation)i;
             }
         }
     }
@@ -82,16 +80,30 @@ static sfBlendEquation equation_from_rb(VALUE rb_equation) {
     return sfBlendEquationAdd;
 }
 
-static VALUE BlendMode_new(int argc, VALUE *argv, VALUE klass) {
+/* call-seq:
+ *   BlendMode.new -> BlendMode(ALPHA)
+ *   BlendMode.new(color_src_factor, color_dst_factor, color_equation, alpha_src_factor,
+ * alpha_dst_factor, alpha_equation) -> BlendMode
+ *
+ * Each factor argument is a Symbol (one of +:zero+, +:one+, +:src_color+,
+ * +:one_minus_src_color+, +:dst_color+, +:one_minus_dst_color+,
+ * +:src_alpha+, +:one_minus_src_alpha+, +:dst_alpha+,
+ * +:one_minus_dst_alpha+) or the equivalent Integer. Each equation argument
+ * is a Symbol (+:add+, +:subtract+, +:reverse_subtract+, +:min+, +:max+) or
+ * the equivalent Integer.
+ *
+ * @return [BlendMode]
+ * @raise [ArgumentError] if given an argument count other than 0 or 6
+ */
+static VALUE BlendMode_new(int argc, VALUE* argv, VALUE klass) {
     VALUE self;
-    BlendMode *ptr;
+    BlendMode* ptr;
     sfBlendMode mode = sfBlendAlpha;
 
     if (argc == 6) {
-        mode = (sfBlendMode) {
-            factor_from_rb(argv[0]), factor_from_rb(argv[1]), equation_from_rb(argv[2]),
-            factor_from_rb(argv[3]), factor_from_rb(argv[4]), equation_from_rb(argv[5])
-        };
+        mode = (sfBlendMode){factor_from_rb(argv[0]),   factor_from_rb(argv[1]),
+                             equation_from_rb(argv[2]), factor_from_rb(argv[3]),
+                             factor_from_rb(argv[4]),   equation_from_rb(argv[5])};
     } else if (argc != 0) {
         raise_invalid_arguments_excepted(6, argc);
     }
@@ -104,81 +116,199 @@ static VALUE BlendMode_new(int argc, VALUE *argv, VALUE klass) {
     return self;
 }
 
+/* call-seq: color_src_factor -> Symbol
+ *
+ * Returns the source blend factor for color components.
+ *
+ * @return [Symbol] the source blending factor for the color/RGB channels
+ */
 static VALUE BlendMode_get_color_src_factor(VALUE self) {
-    return ID2SYM(rb_intern(factor_names[((BlendMode *) Get_BlendMode_Struct(self))->mode.colorSrcFactor]));
+    return ID2SYM(
+        rb_intern(factor_names[((BlendMode*)Get_BlendMode_Struct(self))->mode.colorSrcFactor]));
 }
 
+/* call-seq: color_dst_factor -> Symbol
+ *
+ * Returns the destination blend factor for color components.
+ *
+ * @return [Symbol] the destination blending factor for the color/RGB channels
+ */
 static VALUE BlendMode_get_color_dst_factor(VALUE self) {
-    return ID2SYM(rb_intern(factor_names[((BlendMode *) Get_BlendMode_Struct(self))->mode.colorDstFactor]));
+    return ID2SYM(
+        rb_intern(factor_names[((BlendMode*)Get_BlendMode_Struct(self))->mode.colorDstFactor]));
 }
 
+/* call-seq: color_equation -> Symbol
+ *
+ * Returns the blend equation for color components.
+ *
+ * @return [Symbol] the blending equation for the color/RGB channels
+ */
 static VALUE BlendMode_get_color_equation(VALUE self) {
-    return ID2SYM(rb_intern(equation_names[((BlendMode *) Get_BlendMode_Struct(self))->mode.colorEquation]));
+    return ID2SYM(
+        rb_intern(equation_names[((BlendMode*)Get_BlendMode_Struct(self))->mode.colorEquation]));
 }
 
+/* call-seq: alpha_src_factor -> Symbol
+ *
+ * Returns the source blend factor for alpha.
+ *
+ * @return [Symbol] the source blending factor for the alpha channel
+ */
 static VALUE BlendMode_get_alpha_src_factor(VALUE self) {
-    return ID2SYM(rb_intern(factor_names[((BlendMode *) Get_BlendMode_Struct(self))->mode.alphaSrcFactor]));
+    return ID2SYM(
+        rb_intern(factor_names[((BlendMode*)Get_BlendMode_Struct(self))->mode.alphaSrcFactor]));
 }
 
+/* call-seq: alpha_dst_factor -> Symbol
+ *
+ * Returns the destination blend factor for alpha.
+ *
+ * @return [Symbol] the destination blending factor for the alpha channel
+ */
 static VALUE BlendMode_get_alpha_dst_factor(VALUE self) {
-    return ID2SYM(rb_intern(factor_names[((BlendMode *) Get_BlendMode_Struct(self))->mode.alphaDstFactor]));
+    return ID2SYM(
+        rb_intern(factor_names[((BlendMode*)Get_BlendMode_Struct(self))->mode.alphaDstFactor]));
 }
 
+/* call-seq: alpha_equation -> Symbol
+ *
+ * Returns the blend equation for alpha.
+ *
+ * @return [Symbol] the blending equation for the alpha channel
+ */
 static VALUE BlendMode_get_alpha_equation(VALUE self) {
-    return ID2SYM(rb_intern(equation_names[((BlendMode *) Get_BlendMode_Struct(self))->mode.alphaEquation]));
+    return ID2SYM(
+        rb_intern(equation_names[((BlendMode*)Get_BlendMode_Struct(self))->mode.alphaEquation]));
 }
 
+/* call-seq:
+ *   color_src_factor=(value) -> Symbol
+ *
+ * Sets the source blend factor for color components.
+ *
+ * @return [Symbol] +value+
+ */
 static VALUE BlendMode_set_color_src_factor(VALUE self, VALUE rb_value) {
-    ((BlendMode *) Get_BlendMode_Struct(self))->mode.colorSrcFactor = factor_from_rb(rb_value);
+    rb_check_frozen(self);
+    ((BlendMode*)Get_BlendMode_Struct(self))->mode.colorSrcFactor = factor_from_rb(rb_value);
     return rb_value;
 }
 
+/* call-seq:
+ *   color_dst_factor=(value) -> Symbol
+ *
+ * Sets the destination blend factor for color components.
+ *
+ * @return [Symbol] +value+
+ */
 static VALUE BlendMode_set_color_dst_factor(VALUE self, VALUE rb_value) {
-    ((BlendMode *) Get_BlendMode_Struct(self))->mode.colorDstFactor = factor_from_rb(rb_value);
+    rb_check_frozen(self);
+    ((BlendMode*)Get_BlendMode_Struct(self))->mode.colorDstFactor = factor_from_rb(rb_value);
     return rb_value;
 }
 
+/* call-seq:
+ *   color_equation=(value) -> Symbol
+ *
+ * Sets the blend equation for color components.
+ *
+ * @return [Symbol] +value+
+ */
 static VALUE BlendMode_set_color_equation(VALUE self, VALUE rb_value) {
-    ((BlendMode *) Get_BlendMode_Struct(self))->mode.colorEquation = equation_from_rb(rb_value);
+    rb_check_frozen(self);
+    ((BlendMode*)Get_BlendMode_Struct(self))->mode.colorEquation = equation_from_rb(rb_value);
     return rb_value;
 }
 
+/* call-seq:
+ *   alpha_src_factor=(value) -> Symbol
+ *
+ * Sets the source blend factor for alpha.
+ *
+ * @return [Symbol] +value+
+ */
 static VALUE BlendMode_set_alpha_src_factor(VALUE self, VALUE rb_value) {
-    ((BlendMode *) Get_BlendMode_Struct(self))->mode.alphaSrcFactor = factor_from_rb(rb_value);
+    rb_check_frozen(self);
+    ((BlendMode*)Get_BlendMode_Struct(self))->mode.alphaSrcFactor = factor_from_rb(rb_value);
     return rb_value;
 }
 
+/* call-seq:
+ *   alpha_dst_factor=(value) -> Symbol
+ *
+ * Sets the destination blend factor for alpha.
+ *
+ * @return [Symbol] +value+
+ */
 static VALUE BlendMode_set_alpha_dst_factor(VALUE self, VALUE rb_value) {
-    ((BlendMode *) Get_BlendMode_Struct(self))->mode.alphaDstFactor = factor_from_rb(rb_value);
+    rb_check_frozen(self);
+    ((BlendMode*)Get_BlendMode_Struct(self))->mode.alphaDstFactor = factor_from_rb(rb_value);
     return rb_value;
 }
 
+/* call-seq:
+ *   alpha_equation=(value) -> Symbol
+ *
+ * Sets the blend equation for alpha.
+ *
+ * @return [Symbol] +value+
+ */
 static VALUE BlendMode_set_alpha_equation(VALUE self, VALUE rb_value) {
-    ((BlendMode *) Get_BlendMode_Struct(self))->mode.alphaEquation = equation_from_rb(rb_value);
+    rb_check_frozen(self);
+    ((BlendMode*)Get_BlendMode_Struct(self))->mode.alphaEquation = equation_from_rb(rb_value);
     return rb_value;
 }
 
+/* call-seq:
+ *   self == other -> true or false
+ *
+ * Returns +true+ if the two objects are equal.
+ *
+ * @return [Boolean]
+ */
 static VALUE BlendMode_eql(VALUE self, VALUE rb_other) {
-    sfBlendMode a = ((BlendMode *) Get_BlendMode_Struct(self))->mode;
+    sfBlendMode a = ((BlendMode*)Get_BlendMode_Struct(self))->mode;
     sfBlendMode b;
 
     if (!rb_obj_is_kind_of(rb_other, rb_cBlendMode)) {
         return Qfalse;
     }
 
-    b = ((BlendMode *) Get_BlendMode_Struct(rb_other))->mode;
+    b = ((BlendMode*)Get_BlendMode_Struct(rb_other))->mode;
 
     return BOOL2RB(a.colorSrcFactor == b.colorSrcFactor && a.colorDstFactor == b.colorDstFactor &&
                    a.colorEquation == b.colorEquation && a.alphaSrcFactor == b.alphaSrcFactor &&
                    a.alphaDstFactor == b.alphaDstFactor && a.alphaEquation == b.alphaEquation);
 }
 
-static void BlendMode_define_const(VALUE klass, const char *name, sfBlendMode mode) {
-    rb_define_const(klass, name, BlendMode_wrap(mode));
-}
-
-void Init_BlendMode(VALUE rb_module) {
-    rb_cBlendMode = rb_define_class_under(rb_module, "BlendMode", rb_cObject);
+/* Document-class: SFML::BlendMode
+ * Describes how the colors of a drawn object are combined with the colors
+ * already in the render target, via two triples of (source factor,
+ * destination factor, equation) -- one for the color/RGB channels, one for
+ * the alpha channel.
+ *
+ * @!attribute color_src_factor
+ *   The source blend factor for color components.
+ *   @return [Symbol] the source blending factor for the color channels
+ * @!attribute color_dst_factor
+ *   The destination blend factor for color components.
+ *   @return [Symbol] the destination blending factor for the color channels
+ * @!attribute color_equation
+ *   The blend equation for color components.
+ *   @return [Symbol] the blending equation for the color channels
+ * @!attribute alpha_src_factor
+ *   The source blend factor for alpha.
+ *   @return [Symbol] the source blending factor for the alpha channel
+ * @!attribute alpha_dst_factor
+ *   The destination blend factor for alpha.
+ *   @return [Symbol] the destination blending factor for the alpha channel
+ * @!attribute alpha_equation
+ *   The blend equation for alpha.
+ *   @return [Symbol] the blending equation for the alpha channel
+ */
+void Init_BlendMode(VALUE rb_mSFML) {
+    rb_cBlendMode = rb_define_class_under(rb_mSFML, "BlendMode", rb_cObject);
 
     rb_define_singleton_method(rb_cBlendMode, "new", BlendMode_new, -1);
 
@@ -198,27 +328,47 @@ void Init_BlendMode(VALUE rb_module) {
 
     rb_define_method(rb_cBlendMode, "==", BlendMode_eql, 1);
 
-    BlendMode_define_const(rb_cBlendMode, "NONE", sfBlendNone);
-    BlendMode_define_const(rb_cBlendMode, "ALPHA", sfBlendAlpha);
-    BlendMode_define_const(rb_cBlendMode, "ADD", sfBlendAdd);
-    BlendMode_define_const(rb_cBlendMode, "MULTIPLY", sfBlendMultiply);
-    BlendMode_define_const(rb_cBlendMode, "MIN", sfBlendMin);
-    BlendMode_define_const(rb_cBlendMode, "MAX", sfBlendMax);
+    /* No blending: source pixels overwrite destination pixels unchanged
+     * (One, Zero, Add for both the color and alpha channels). */
+    rb_define_const(rb_cBlendMode, "NONE", rb_obj_freeze(BlendMode_wrap(sfBlendNone)));
+
+    /* Standard alpha blending: the source is blended over the destination
+     * using the source alpha (SrcAlpha, OneMinusSrcAlpha, Add for color;
+     * One, OneMinusSrcAlpha, Add for alpha). The default blend mode. */
+    rb_define_const(rb_cBlendMode, "ALPHA", rb_obj_freeze(BlendMode_wrap(sfBlendAlpha)));
+
+    /* Additive blending: the source color, scaled by its alpha, is added to
+     * the destination (SrcAlpha, One, Add for color; One, One, Add for
+     * alpha). */
+    rb_define_const(rb_cBlendMode, "ADD", rb_obj_freeze(BlendMode_wrap(sfBlendAdd)));
+
+    /* Multiplicative blending: source and destination colors are multiplied
+     * together (DstColor, Zero, Add for both the color and alpha
+     * channels). */
+    rb_define_const(rb_cBlendMode, "MULTIPLY", rb_obj_freeze(BlendMode_wrap(sfBlendMultiply)));
+
+    /* Component-wise minimum of the source and destination colors (One,
+     * One, Min for both the color and alpha channels). */
+    rb_define_const(rb_cBlendMode, "MIN", rb_obj_freeze(BlendMode_wrap(sfBlendMin)));
+
+    /* Component-wise maximum of the source and destination colors (One,
+     * One, Max for both the color and alpha channels). */
+    rb_define_const(rb_cBlendMode, "MAX", rb_obj_freeze(BlendMode_wrap(sfBlendMax)));
 }
 
 VALUE Get_Klass_BlendMode(void) {
     return rb_cBlendMode;
 }
 
-void *Get_BlendMode_Struct(VALUE self) {
-    BlendMode *ptr;
+void* Get_BlendMode_Struct(VALUE self) {
+    BlendMode* ptr;
     TypedData_Get_Struct(self, BlendMode, &BlendMode_data_type, ptr);
     return ptr;
 }
 
 sfBlendMode blend_mode_from_rb(VALUE rb_mode) {
     if (rb_obj_is_kind_of(rb_mode, rb_cBlendMode)) {
-        return ((BlendMode *) Get_BlendMode_Struct(rb_mode))->mode;
+        return ((BlendMode*)Get_BlendMode_Struct(rb_mode))->mode;
     }
 
     if (RB_INTEGER_TYPE_P(rb_mode) == 0 && !SYMBOL_P(rb_mode)) {
@@ -226,7 +376,7 @@ sfBlendMode blend_mode_from_rb(VALUE rb_mode) {
     }
 
     if (SYMBOL_P(rb_mode)) {
-        const char *name = rb_id2name(SYM2ID(rb_mode));
+        const char* name = rb_id2name(SYM2ID(rb_mode));
 
         if (strcmp(name, "none") == 0) {
             return sfBlendNone;