sfml3-rb 0.2.2 → 0.3.0

data/ext/graphics/stencil_mode.c

@@ -13,26 +13,23 @@ typedef struct {
 
 static VALUE rb_cStencilMode;
 
-static const char *comparison_names[] = {
-    "never", "less", "less_equal", "greater", "greater_equal", "equal", "not_equal", "always"
-};
+static const char* comparison_names[] = {"never",         "less",  "less_equal", "greater",
+                                         "greater_equal", "equal", "not_equal",  "always"};
 
-static const char *operation_names[] = {
-    "keep", "zero", "replace", "increment", "decrement", "invert"
-};
+static const char* operation_names[] = {"keep",      "zero",      "replace",
+                                        "increment", "decrement", "invert"};
 
-static void StencilMode_free(void *ptr) {
+static void StencilMode_free(void* ptr) {
     free(ptr);
 }
 
 static const rb_data_type_t StencilMode_data_type = {
     .wrap_struct_name = "SFML::StencilMode",
     .function = {.dmark = NULL, .dfree = StencilMode_free, .dsize = NULL},
-    .flags = RUBY_TYPED_FREE_IMMEDIATELY
-};
+    .flags = RUBY_TYPED_FREE_IMMEDIATELY};
 
 static VALUE StencilMode_wrap(sfStencilMode mode) {
-    StencilMode *ptr = malloc(sizeof(StencilMode));
+    StencilMode* ptr = malloc(sizeof(StencilMode));
 
     ptr->mode = mode;
 
@@ -43,15 +40,15 @@ static sfStencilComparison comparison_from_rb(VALUE rb_value) {
     size_t i;
 
     if (RB_INTEGER_TYPE_P(rb_value)) {
-        return (sfStencilComparison) NUM2INT(rb_value);
+        return (sfStencilComparison)NUM2INT(rb_value);
     }
 
     if (SYMBOL_P(rb_value)) {
-        const char *name = rb_id2name(SYM2ID(rb_value));
+        const char* name = rb_id2name(SYM2ID(rb_value));
 
         for (i = 0; i < sizeof(comparison_names) / sizeof(comparison_names[0]); i++) {
             if (strcmp(name, comparison_names[i]) == 0) {
-                return (sfStencilComparison) i;
+                return (sfStencilComparison)i;
             }
         }
     }
@@ -64,15 +61,15 @@ static sfStencilUpdateOperation operation_from_rb(VALUE rb_value) {
     size_t i;
 
     if (RB_INTEGER_TYPE_P(rb_value)) {
-        return (sfStencilUpdateOperation) NUM2INT(rb_value);
+        return (sfStencilUpdateOperation)NUM2INT(rb_value);
     }
 
     if (SYMBOL_P(rb_value)) {
-        const char *name = rb_id2name(SYM2ID(rb_value));
+        const char* name = rb_id2name(SYM2ID(rb_value));
 
         for (i = 0; i < sizeof(operation_names) / sizeof(operation_names[0]); i++) {
             if (strcmp(name, operation_names[i]) == 0) {
-                return (sfStencilUpdateOperation) i;
+                return (sfStencilUpdateOperation)i;
             }
         }
     }
@@ -81,16 +78,28 @@ static sfStencilUpdateOperation operation_from_rb(VALUE rb_value) {
     return sfStencilUpdateOperationKeep;
 }
 
-static VALUE StencilMode_new(int argc, VALUE *argv, VALUE klass) {
+/* call-seq:
+ *   StencilMode.new -> StencilMode
+ *   StencilMode.new(comparison, update_operation, reference, mask, stencil_only) -> StencilMode
+ *
+ * With no arguments, builds the default stencil mode (always passes,
+ * doesn't modify the stencil buffer). +comparison+ and +update_operation+
+ * accept either a Symbol (see #comparison and #update_operation) or the
+ * matching CSFML Integer constant.
+ *
+ * @return [StencilMode]
+ * @raise [ArgumentError] if given an argument count other than 0 or 5
+ */
+static VALUE StencilMode_new(int argc, VALUE* argv, VALUE klass) {
     VALUE self;
-    StencilMode *ptr;
+    StencilMode* ptr;
     sfStencilMode mode = sfStencilMode_default;
 
     if (argc == 5) {
         mode.stencilComparison = comparison_from_rb(argv[0]);
         mode.stencilUpdateOperation = operation_from_rb(argv[1]);
-        mode.stencilReference.value = (unsigned int) NUM2UINT(argv[2]);
-        mode.stencilMask.value = (unsigned int) NUM2UINT(argv[3]);
+        mode.stencilReference.value = (unsigned int)NUM2UINT(argv[2]);
+        mode.stencilMask.value = (unsigned int)NUM2UINT(argv[3]);
         mode.stencilOnly = RTEST(argv[4]);
     } else if (argc != 0) {
         raise_invalid_arguments_excepted(5, argc);
@@ -104,72 +113,172 @@ static VALUE StencilMode_new(int argc, VALUE *argv, VALUE klass) {
     return self;
 }
 
+/* call-seq: comparison -> Symbol
+ *
+ * Returns the comparison used against the stencil buffer.
+ *
+ * @return [Symbol] one of :never, :less, :less_equal, :greater,
+ *   :greater_equal, :equal, :not_equal, :always
+ */
 static VALUE StencilMode_get_comparison(VALUE self) {
-    return ID2SYM(rb_intern(comparison_names[((StencilMode *) Get_StencilMode_Struct(self))->mode.stencilComparison]));
+    return ID2SYM(rb_intern(
+        comparison_names[((StencilMode*)Get_StencilMode_Struct(self))->mode.stencilComparison]));
 }
 
+/* call-seq: update_operation -> Symbol
+ *
+ * Returns the operation applied when the stencil test passes or fails.
+ *
+ * @return [Symbol] one of :keep, :zero, :replace, :increment, :decrement,
+ *   :invert
+ */
 static VALUE StencilMode_get_operation(VALUE self) {
-    sfStencilMode mode = ((StencilMode *) Get_StencilMode_Struct(self))->mode;
+    sfStencilMode mode = ((StencilMode*)Get_StencilMode_Struct(self))->mode;
 
     return ID2SYM(rb_intern(operation_names[mode.stencilUpdateOperation]));
 }
 
+/* call-seq: reference -> Integer
+ *
+ * Returns the reference value compared against the stencil buffer.
+ *
+ * @return [Integer]
+ */
 static VALUE StencilMode_get_reference(VALUE self) {
-    return UINT2NUM(((StencilMode *) Get_StencilMode_Struct(self))->mode.stencilReference.value);
+    return UINT2NUM(((StencilMode*)Get_StencilMode_Struct(self))->mode.stencilReference.value);
 }
 
+/* call-seq: mask -> Integer
+ *
+ * Returns the bitmask applied to the stencil values.
+ *
+ * @return [Integer]
+ */
 static VALUE StencilMode_get_mask(VALUE self) {
-    return UINT2NUM(((StencilMode *) Get_StencilMode_Struct(self))->mode.stencilMask.value);
+    return UINT2NUM(((StencilMode*)Get_StencilMode_Struct(self))->mode.stencilMask.value);
 }
 
+/* call-seq: stencil_only -> true or false
+ *
+ * Returns +true+ if only the stencil buffer is written to.
+ *
+ * @return [Boolean]
+ */
 static VALUE StencilMode_get_only(VALUE self) {
-    return BOOL2RB(((StencilMode *) Get_StencilMode_Struct(self))->mode.stencilOnly);
+    return BOOL2RB(((StencilMode*)Get_StencilMode_Struct(self))->mode.stencilOnly);
 }
 
+/* call-seq:
+ *   comparison=(value) -> Symbol or Integer
+ *
+ * Sets the comparison used against the stencil buffer.
+ *
+ * @return [Symbol, Integer] +value+
+ */
 static VALUE StencilMode_set_comparison(VALUE self, VALUE rb_value) {
-    ((StencilMode *) Get_StencilMode_Struct(self))->mode.stencilComparison = comparison_from_rb(rb_value);
+    ((StencilMode*)Get_StencilMode_Struct(self))->mode.stencilComparison =
+        comparison_from_rb(rb_value);
     return rb_value;
 }
 
+/* call-seq:
+ *   update_operation=(value) -> Symbol or Integer
+ *
+ * Sets the operation applied when the stencil test passes or fails.
+ *
+ * @return [Symbol, Integer] +value+
+ */
 static VALUE StencilMode_set_operation(VALUE self, VALUE rb_value) {
-    ((StencilMode *) Get_StencilMode_Struct(self))->mode.stencilUpdateOperation = operation_from_rb(rb_value);
+    ((StencilMode*)Get_StencilMode_Struct(self))->mode.stencilUpdateOperation =
+        operation_from_rb(rb_value);
     return rb_value;
 }
 
+/* call-seq:
+ *   reference=(value) -> Integer
+ *
+ * Sets the reference value compared against the stencil buffer.
+ *
+ * @return [Integer] +value+
+ */
 static VALUE StencilMode_set_reference(VALUE self, VALUE rb_value) {
-    ((StencilMode *) Get_StencilMode_Struct(self))->mode.stencilReference.value = (unsigned int) NUM2UINT(rb_value);
+    ((StencilMode*)Get_StencilMode_Struct(self))->mode.stencilReference.value =
+        (unsigned int)NUM2UINT(rb_value);
     return rb_value;
 }
 
+/* call-seq:
+ *   mask=(value) -> Integer
+ *
+ * Sets the bitmask applied to the stencil values.
+ *
+ * @return [Integer] +value+
+ */
 static VALUE StencilMode_set_mask(VALUE self, VALUE rb_value) {
-    ((StencilMode *) Get_StencilMode_Struct(self))->mode.stencilMask.value = (unsigned int) NUM2UINT(rb_value);
+    ((StencilMode*)Get_StencilMode_Struct(self))->mode.stencilMask.value =
+        (unsigned int)NUM2UINT(rb_value);
     return rb_value;
 }
 
+/* call-seq:
+ *   stencil_only=(value) -> true or false
+ *
+ * Enables or disables writing only to the stencil buffer.
+ *
+ * @return [Boolean] +value+
+ */
 static VALUE StencilMode_set_only(VALUE self, VALUE rb_value) {
-    ((StencilMode *) Get_StencilMode_Struct(self))->mode.stencilOnly = RTEST(rb_value);
+    ((StencilMode*)Get_StencilMode_Struct(self))->mode.stencilOnly = RTEST(rb_value);
     return rb_value;
 }
 
+/* call-seq:
+ *   self == other -> true or false
+ *
+ * Returns +true+ if the two objects are equal.
+ *
+ * @return [Boolean]
+ */
 static VALUE StencilMode_eql(VALUE self, VALUE rb_other) {
-    sfStencilMode a = ((StencilMode *) Get_StencilMode_Struct(self))->mode;
+    sfStencilMode a = ((StencilMode*)Get_StencilMode_Struct(self))->mode;
     sfStencilMode b;
 
     if (!rb_obj_is_kind_of(rb_other, rb_cStencilMode)) {
         return Qfalse;
     }
 
-    b = ((StencilMode *) Get_StencilMode_Struct(rb_other))->mode;
+    b = ((StencilMode*)Get_StencilMode_Struct(rb_other))->mode;
 
     return BOOL2RB(a.stencilComparison == b.stencilComparison &&
                    a.stencilUpdateOperation == b.stencilUpdateOperation &&
                    a.stencilReference.value == b.stencilReference.value &&
-                   a.stencilMask.value == b.stencilMask.value &&
-                   a.stencilOnly == b.stencilOnly);
+                   a.stencilMask.value == b.stencilMask.value && a.stencilOnly == b.stencilOnly);
 }
 
-void Init_StencilMode(VALUE rb_module) {
-    rb_cStencilMode = rb_define_class_under(rb_module, "StencilMode", rb_cObject);
+/* Document-class: SFML::StencilMode
+ * Configures how the stencil buffer is used and updated when drawing,
+ * carried on RenderState#stencil_mode.
+ *
+ * @!attribute comparison
+ *   The comparison used against the stencil buffer.
+ *   @return [Symbol] one of :never, :less, :less_equal, :greater,
+ *     :greater_equal, :equal, :not_equal, :always
+ * @!attribute update_operation
+ *   The operation applied when the stencil test passes or fails.
+ *   @return [Symbol] one of :keep, :zero, :replace, :increment, :decrement,
+ *     :invert
+ * @!attribute reference
+ *   The reference value compared against the stencil buffer.
+ *   @return [Integer]
+ * @!attribute mask
+ *   The bitmask applied to the stencil values.
+ *   @return [Integer]
+ * @!attribute stencil_only
+ *   Whether only the stencil buffer is written to.
+ *   @return [Boolean]
+ */
+void Init_StencilMode(VALUE rb_mSFML) {
+    rb_cStencilMode = rb_define_class_under(rb_mSFML, "StencilMode", rb_cObject);
 
     rb_define_singleton_method(rb_cStencilMode, "new", StencilMode_new, -1);
 
@@ -192,15 +301,15 @@ VALUE Get_Klass_StencilMode(void) {
     return rb_cStencilMode;
 }
 
-void *Get_StencilMode_Struct(VALUE self) {
-    StencilMode *ptr;
+void* Get_StencilMode_Struct(VALUE self) {
+    StencilMode* ptr;
     TypedData_Get_Struct(self, StencilMode, &StencilMode_data_type, ptr);
     return ptr;
 }
 
 sfStencilMode stencil_mode_from_rb(VALUE rb_mode) {
     if (rb_obj_is_kind_of(rb_mode, rb_cStencilMode)) {
-        return ((StencilMode *) Get_StencilMode_Struct(rb_mode))->mode;
+        return ((StencilMode*)Get_StencilMode_Struct(rb_mode))->mode;
     }
 
     return sfStencilMode_default;

data/ext/graphics/target.c

@@ -12,34 +12,46 @@
 
 static VALUE rb_cTarget;
 
-static Target *Target_create(TargetType type, void *handle) {
-    Target *target = malloc(sizeof(Target));
+static Target* Target_create(TargetType type, void* handle, VALUE rb_source) {
+    Target* target = malloc(sizeof(Target));
 
     target->type = type;
     target->handle = handle;
+    target->rb_source = rb_source;
 
     return target;
 }
 
-static void RenderTarget_free(void *ptr) {
+static void RenderTarget_mark(void* ptr) {
+    rb_gc_mark(((Target*)ptr)->rb_source);
+}
+
+static void RenderTarget_free(void* ptr) {
     free(ptr);
 }
 
 static const rb_data_type_t RenderTarget_data_type = {
     .wrap_struct_name = "SFML::Target",
-    .function = {.dmark = NULL, .dfree = RenderTarget_free, .dsize = NULL},
-    .flags = RUBY_TYPED_FREE_IMMEDIATELY
-};
-
+    .function = {.dmark = RenderTarget_mark, .dfree = RenderTarget_free, .dsize = NULL},
+    .flags = RUBY_TYPED_FREE_IMMEDIATELY};
+
+/* call-seq:
+ *   Target.new(window) -> Target
+ *
+ * Wraps +window+ (a Window) as a generic render target.
+ *
+ * @return [Target]
+ * @raise [TypeError] if +window+ is not a Window
+ */
 static VALUE RenderTarget_new(VALUE klass, VALUE rb_window) {
     VALUE self;
-    Target *target;
+    Target* target;
 
     if (!rb_obj_is_kind_of(rb_window, Get_Klass_Window())) {
         raise_invalid_argument_class(Get_Klass_Window());
     }
 
-    target = Target_create(SFML_TARGET_WINDOW, Get_Window_Struct(rb_window));
+    target = Target_create(SFML_TARGET_WINDOW, Get_Window_Struct(rb_window), rb_window);
     self = TypedData_Wrap_Struct(klass, &RenderTarget_data_type, target);
 
     rb_obj_call_init(self, 0, NULL);
@@ -51,6 +63,15 @@ static VALUE RenderTarget_init(VALUE self) {
     return self;
 }
 
+/* call-seq:
+ *   draw(drawable, state) -> void
+ *
+ * Draws +drawable+ (any object responding to +#draw+, i.e. including
+ * Drawable) onto this target using +state+ (a RenderState).
+ *
+ * @return [nil]
+ * @raise [TypeError] if +state+ is not a RenderState
+ */
 static VALUE RenderTarget_draw(VALUE self, VALUE rb_drawable, VALUE rb_state) {
     if (!rb_obj_is_kind_of(rb_state, Get_Klass_RenderState())) {
         raise_invalid_argument_class(Get_Klass_RenderState());
@@ -59,37 +80,60 @@ static VALUE RenderTarget_draw(VALUE self, VALUE rb_drawable, VALUE rb_state) {
     return rb_funcall(rb_drawable, rb_intern("draw"), 2, self, rb_state);
 }
 
+/* call-seq:
+ *   view=(value) -> nil
+ *
+ * Sets the target's current view.
+ *
+ * @return [nil]
+ * @raise [TypeError] if +value+ is not a View
+ */
 static VALUE RenderTarget_set_view(VALUE self, VALUE rb_view) {
-    Target *target = Get_Target_Struct(self);
+    Target* target = Get_Target_Struct(self);
 
     if (!rb_obj_is_kind_of(rb_view, Get_Klass_View())) {
         raise_invalid_argument_class(Get_Klass_View());
     }
 
     if (target->type == SFML_TARGET_WINDOW) {
-        sfRenderWindow_setView((sfRenderWindow *) target->handle, Get_View_Struct(rb_view));
+        sfRenderWindow_setView((sfRenderWindow*)target->handle, Get_View_Struct(rb_view));
     } else {
-        sfRenderTexture_setView((sfRenderTexture *) target->handle, Get_View_Struct(rb_view));
+        sfRenderTexture_setView((sfRenderTexture*)target->handle, Get_View_Struct(rb_view));
     }
 
     return Qnil;
 }
 
+/* call-seq: view -> View
+ *
+ * Returns the target's current view.
+ *
+ * @return [View] a copy of the target's current view
+ */
 static VALUE RenderTarget_get_view(VALUE self) {
-    Target *target = Get_Target_Struct(self);
-    sfView *view;
+    Target* target = Get_Target_Struct(self);
+    sfView* view;
 
     if (target->type == SFML_TARGET_WINDOW) {
-        view = sfView_copy(sfRenderWindow_getView((sfRenderWindow *) target->handle));
+        view = sfView_copy(sfRenderWindow_getView((sfRenderWindow*)target->handle));
     } else {
-        view = sfView_copy(sfRenderTexture_getView((sfRenderTexture *) target->handle));
+        view = sfView_copy(sfRenderTexture_getView((sfRenderTexture*)target->handle));
     }
 
     return Get_Casting_View(view);
 }
 
-void Init_Target(VALUE rb_module) {
-    rb_cTarget = rb_define_class_under(rb_module, "Target", rb_cObject);
+/* Document-class: SFML::Target
+ * A generic handle onto whatever can be drawn to -- a Window or a
+ * RenderTexture -- used by Drawable#draw so drawable objects don't need to
+ * know which concrete kind of target they're being drawn onto.
+ *
+ * @!attribute view
+ *   The target's current view.
+ *   @return [View]
+ */
+void Init_Target(VALUE rb_mSFML) {
+    rb_cTarget = rb_define_class_under(rb_mSFML, "Target", rb_cObject);
 
     rb_define_singleton_method(rb_cTarget, "new", RenderTarget_new, 1);
 
@@ -108,8 +152,8 @@ VALUE Get_Klass_Target(void) {
     return rb_cTarget;
 }
 
-Target *Get_Target_Struct(VALUE self) {
-    Target *ptr;
+Target* Get_Target_Struct(VALUE self) {
+    Target* ptr;
     TypedData_Get_Struct(self, Target, &RenderTarget_data_type, ptr);
     return ptr;
 }
@@ -120,13 +164,14 @@ VALUE Get_New_Target(VALUE rb_window) {
 
 VALUE Get_New_Target_From_RenderTexture(VALUE rb_render_texture) {
     VALUE self;
-    Target *target;
+    Target* target;
 
     if (!rb_obj_is_kind_of(rb_render_texture, Get_Klass_RenderTexture())) {
         raise_invalid_argument_class(Get_Klass_RenderTexture());
     }
 
-    target = Target_create(SFML_TARGET_TEXTURE, Get_RenderTexture_Struct(rb_render_texture));
+    target = Target_create(SFML_TARGET_TEXTURE, Get_RenderTexture_Struct(rb_render_texture),
+                           rb_render_texture);
     self = TypedData_Wrap_Struct(rb_cTarget, &RenderTarget_data_type, target);
 
     return self;

data/ext/graphics/target.h

@@ -5,36 +5,36 @@
 
 #include "core/sfml.h"
 
-typedef enum {
-    SFML_TARGET_WINDOW,
-    SFML_TARGET_TEXTURE
-} TargetType;
+typedef enum { SFML_TARGET_WINDOW, SFML_TARGET_TEXTURE } TargetType;
 
 typedef struct {
     TargetType type;
-    void *handle;
+    void* handle;
+    /* The Window/RenderTexture `handle` is borrowed from, kept alive for as
+       long as this Target references it -- see Target_mark in target.c. */
+    VALUE rb_source;
 } Target;
 
 /* Dispatch a draw call to whichever underlying render surface this target
    wraps. Pass NULL states to use the defaults; never hand CSFML a NULL. */
-#define TARGET_DRAW(target, window_fn, texture_fn, object, states)                        \
-    do {                                                                                  \
-        const sfRenderStates *sfml_states = (states) ? (states) : &sfRenderStates_default; \
-        if ((target)->type == SFML_TARGET_WINDOW) {                                       \
-            window_fn((sfRenderWindow *) (target)->handle, (object), sfml_states);        \
-        } else {                                                                          \
-            texture_fn((sfRenderTexture *) (target)->handle, (object), sfml_states);      \
-        }                                                                                 \
+#define TARGET_DRAW(target, window_fn, texture_fn, object, states)                                 \
+    do {                                                                                           \
+        const sfRenderStates* sfml_states = (states) ? (states) : &sfRenderStates_default;         \
+        if ((target)->type == SFML_TARGET_WINDOW) {                                                \
+            window_fn((sfRenderWindow*)(target)->handle, (object), sfml_states);                   \
+        } else {                                                                                   \
+            texture_fn((sfRenderTexture*)(target)->handle, (object), sfml_states);                 \
+        }                                                                                          \
     } while (0)
 
 void Init_Target(VALUE rb_module);
 
 VALUE Get_Klass_Target(void);
 
-Target *Get_Target_Struct(VALUE self);
+Target* Get_Target_Struct(VALUE self);
 
 VALUE Get_New_Target(VALUE rb_window);
 
 VALUE Get_New_Target_From_RenderTexture(VALUE rb_render_texture);
 
-#endif //SFML_RB_GRAPHICS_TARGET_H
+#endif // SFML_RB_GRAPHICS_TARGET_H