sfml3-rb 0.2.2 → 0.3.0

data/ext/graphics/vertex_array.c

@@ -14,17 +14,16 @@
 
 static VALUE rb_cVertexArray;
 
-static void VertexArray_free(void *ptr) {
+static void VertexArray_free(void* ptr) {
     sfVertexArray_destroy(ptr);
 }
 
 static const rb_data_type_t VertexArray_data_type = {
     .wrap_struct_name = "SFML::VertexArray",
     .function = {.dmark = NULL, .dfree = VertexArray_free, .dsize = NULL},
-    .flags = RUBY_TYPED_FREE_IMMEDIATELY
-};
+    .flags = RUBY_TYPED_FREE_IMMEDIATELY};
 
-static VALUE VertexArray_wrap(VALUE klass, sfVertexArray *array) {
+static VALUE VertexArray_wrap(VALUE klass, sfVertexArray* array) {
     if (array == NULL) {
         rb_raise(rb_eRuntimeError, "failed to create vertex array");
     }
@@ -32,61 +31,163 @@ static VALUE VertexArray_wrap(VALUE klass, sfVertexArray *array) {
     return TypedData_Wrap_Struct(klass, &VertexArray_data_type, array);
 }
 
-static sfVertexArray *Get_VertexArray_Struct(VALUE self) {
-    sfVertexArray *ptr;
+static sfVertexArray* Get_VertexArray_Struct(VALUE self) {
+    sfVertexArray* ptr;
     TypedData_Get_Struct(self, sfVertexArray, &VertexArray_data_type, ptr);
     return ptr;
 }
 
+/* call-seq:
+ *   VertexArray.new -> VertexArray
+ *
+ * Creates a vertex array using the given +primitive+ type.
+ *
+ * @return [VertexArray] an empty array of :points primitives
+ */
 static VALUE VertexArray_new(VALUE klass) {
     return VertexArray_wrap(klass, sfVertexArray_create());
 }
 
+/* call-seq: copy -> VertexArray
+ *
+ * Returns a deep copy of the object.
+ *
+ * @return [VertexArray] an independent copy
+ */
 static VALUE VertexArray_copy(VALUE self) {
-    return VertexArray_wrap(Get_Klass_VertexArray(), sfVertexArray_copy(Get_VertexArray_Struct(self)));
+    return VertexArray_wrap(Get_Klass_VertexArray(),
+                            sfVertexArray_copy(Get_VertexArray_Struct(self)));
 }
 
+/* call-seq: vertex_count -> Integer
+ *
+ * Returns the number of vertices stored.
+ *
+ * @return [Integer]
+ */
 static VALUE VertexArray_get_vertex_count(VALUE self) {
     return SIZET2NUM(sfVertexArray_getVertexCount(Get_VertexArray_Struct(self)));
 }
 
-static VALUE VertexArray_get_vertex(VALUE self, VALUE rb_index) {
-    return vertex_to_rb(*sfVertexArray_getVertex(Get_VertexArray_Struct(self), (size_t) NUM2SIZET(rb_index)));
+static size_t VertexArray_check_index(VALUE self, VALUE rb_index) {
+    void* array = Get_VertexArray_Struct(self);
+    size_t index = (size_t)NUM2SIZET(rb_index);
+    size_t count = sfVertexArray_getVertexCount(array);
+
+    if (index >= count) {
+        rb_raise(rb_eIndexError, "index %zu outside of vertex count %zu", index, count);
+    }
+
+    return index;
 }
 
+/* call-seq:
+ *   vertex(index) -> Vertex
+ *
+ * Returns the vertex at +index+.
+ *
+ * @return [Vertex] a copy of the vertex at +index+
+ * @raise [IndexError] if +index+ is out of range
+ */
+static VALUE VertexArray_get_vertex(VALUE self, VALUE rb_index) {
+    return vertex_to_rb(*sfVertexArray_getVertex(Get_VertexArray_Struct(self),
+                                                 VertexArray_check_index(self, rb_index)));
+}
+
+/* call-seq:
+ *   set_vertex(index, vertex) -> Vertex
+ *
+ * Replaces the vertex at +index+ with +vertex+.
+ *
+ * @return [Vertex] +vertex+
+ * @raise [IndexError] if +index+ is out of range
+ */
 static VALUE VertexArray_set_vertex(VALUE self, VALUE rb_index, VALUE rb_vertex) {
-    *sfVertexArray_getVertex(Get_VertexArray_Struct(self), (size_t) NUM2SIZET(rb_index)) = vertex_from_rb(rb_vertex);
+    *sfVertexArray_getVertex(Get_VertexArray_Struct(self),
+                             VertexArray_check_index(self, rb_index)) = vertex_from_rb(rb_vertex);
     return rb_vertex;
 }
 
+/* call-seq:
+ *   append(vertex) -> self
+ *
+ * Appends +vertex+ to the array.
+ *
+ * @return [self]
+ */
 static VALUE VertexArray_append(VALUE self, VALUE rb_vertex) {
     sfVertexArray_append(Get_VertexArray_Struct(self), vertex_from_rb(rb_vertex));
     return self;
 }
 
+/* call-seq: clear! -> self
+ *
+ * Removes all vertices.
+ *
+ * @return [self]
+ */
 static VALUE VertexArray_clear(VALUE self) {
     sfVertexArray_clear(Get_VertexArray_Struct(self));
     return self;
 }
 
+/* call-seq:
+ *   resize(count) -> self
+ *
+ * Grows or shrinks the array to +count+ vertices; new vertices are default
+ * ones.
+ *
+ * @return [self]
+ */
 static VALUE VertexArray_resize(VALUE self, VALUE rb_count) {
-    sfVertexArray_resize(Get_VertexArray_Struct(self), (size_t) NUM2SIZET(rb_count));
+    sfVertexArray_resize(Get_VertexArray_Struct(self), (size_t)NUM2SIZET(rb_count));
     return self;
 }
 
+/* call-seq: primitive -> Symbol
+ *
+ * Returns the primitive type used to draw the vertices.
+ *
+ * @return [Symbol] the primitive type vertices are interpreted as (e.g.
+ *   :points, :lines, :triangles)
+ */
 static VALUE VertexArray_get_primitive_type(VALUE self) {
-    return ID2SYM(rb_intern(primitive_type_name(sfVertexArray_getPrimitiveType(Get_VertexArray_Struct(self)))));
+    return ID2SYM(rb_intern(
+        primitive_type_name(sfVertexArray_getPrimitiveType(Get_VertexArray_Struct(self)))));
 }
 
+/* call-seq:
+ *   primitive=(value) -> Symbol
+ *
+ * Sets the primitive type used to draw the vertices.
+ *
+ * @return [Symbol] +value+
+ */
 static VALUE VertexArray_set_primitive_type(VALUE self, VALUE rb_type) {
     sfVertexArray_setPrimitiveType(Get_VertexArray_Struct(self), primitive_type_from_rb(rb_type));
     return rb_type;
 }
 
+/* call-seq: bounds -> Rect
+ *
+ * Returns the axis-aligned bounding box of all vertices.
+ *
+ * @return [Rect] the axis-aligned bounding box of all vertices
+ */
 static VALUE VertexArray_get_bounds(VALUE self) {
     return rect_to_rb(sfVertexArray_getBounds(Get_VertexArray_Struct(self)));
 }
 
+/* call-seq:
+ *   draw(target, state) -> nil
+ *
+ * Part of the Drawable interface; call Target#draw instead of this
+ * directly.
+ *
+ * @return [nil]
+ * @raise [TypeError] if +target+ is not a Target or +state+ is not a
+ *   RenderState
+ */
 static VALUE VertexArray_draw(VALUE self, VALUE rb_target, VALUE rb_state) {
     if (!rb_obj_is_kind_of(rb_target, Get_Klass_Target())) {
         raise_invalid_argument_class(Get_Klass_Target());
@@ -96,14 +197,25 @@ static VALUE VertexArray_draw(VALUE self, VALUE rb_target, VALUE rb_state) {
         raise_invalid_argument_class(Get_Klass_RenderState());
     }
 
-    TARGET_DRAW(Get_Target_Struct(rb_target), sfRenderWindow_drawVertexArray, sfRenderTexture_drawVertexArray,
-                Get_VertexArray_Struct(self), Get_RenderState_Struct(rb_state));
+    TARGET_DRAW(Get_Target_Struct(rb_target), sfRenderWindow_drawVertexArray,
+                sfRenderTexture_drawVertexArray, Get_VertexArray_Struct(self),
+                Get_RenderState_Struct(rb_state));
 
     return Qnil;
 }
 
-void Init_VertexArray(VALUE rb_module) {
-    rb_cVertexArray = rb_define_class_under(rb_module, "VertexArray", rb_cObject);
+/* Document-class: SFML::VertexArray
+ * A resizable, drawable set of Vertex objects interpreted as a given
+ * primitive type (points, lines, triangles, ...).
+ *
+ * Includes +Drawable+.
+ *
+ * @!attribute primitive
+ *   The primitive type used to draw the vertices.
+ *   @return [Symbol]
+ */
+void Init_VertexArray(VALUE rb_mSFML) {
+    rb_cVertexArray = rb_define_class_under(rb_mSFML, "VertexArray", rb_cObject);
 
     rb_include_module(rb_cVertexArray, Get_Module_Drawable());
 

data/ext/graphics/vertex_buffer.c

@@ -60,6 +60,20 @@ static sfVertexBufferUsage usage_from_rb(VALUE rb_usage) {
     return sfVertexBufferStatic;
 }
 
+/* call-seq:
+ *   VertexBuffer.new                                    -> VertexBuffer
+ *   VertexBuffer.new(count)                             -> VertexBuffer
+ *   VertexBuffer.new(count, primitive)                  -> VertexBuffer
+ *   VertexBuffer.new(count, primitive, usage)            -> VertexBuffer
+ *
+ * Creates a GPU-side vertex buffer holding +count+ vertices (default 0),
+ * interpreted as +primitive+ (default :points, see VertexArray#primitive),
+ * with the given +usage+ hint (one of :stream, :dynamic, :static; default
+ * :static).
+ *
+ * @return [VertexBuffer]
+ * @raise [RuntimeError] if creation fails
+ */
 static VALUE VertexBuffer_new(int argc, VALUE* argv, VALUE klass) {
     VALUE rb_count, rb_primitive, rb_usage;
     size_t count = 0;
@@ -83,15 +97,37 @@ static VALUE VertexBuffer_new(int argc, VALUE* argv, VALUE klass) {
     return VertexBuffer_wrap(klass, sfVertexBuffer_create(count, primitive, usage));
 }
 
+/* call-seq: copy -> VertexBuffer
+ *
+ * Returns a deep copy of the object.
+ *
+ * @return [VertexBuffer] an independent copy
+ */
 static VALUE VertexBuffer_copy(VALUE self) {
     return VertexBuffer_wrap(Get_Klass_VertexBuffer(),
                              sfVertexBuffer_copy(Get_VertexBuffer_Struct(self)));
 }
 
+/* call-seq: vertex_count -> Integer
+ *
+ * Returns the number of vertices stored.
+ *
+ * @return [Integer]
+ */
 static VALUE VertexBuffer_get_vertex_count(VALUE self) {
     return SIZET2NUM(sfVertexBuffer_getVertexCount(Get_VertexBuffer_Struct(self)));
 }
 
+/* call-seq:
+ *   update(vertices)         -> true or false
+ *   update(vertices, offset) -> true or false
+ *
+ * Uploads +vertices+ (an Array of Vertex, or of anything Vertex.new
+ * accepts) into the buffer starting at +offset+ (default 0). The buffer
+ * must have enough room; use #resize (via .new) if not.
+ *
+ * @return [Boolean] whether the update succeeded
+ */
 static VALUE VertexBuffer_update(int argc, VALUE* argv, VALUE self) {
     VALUE rb_vertices, rb_offset;
     unsigned int offset = 0;
@@ -115,6 +151,15 @@ static VALUE VertexBuffer_update(int argc, VALUE* argv, VALUE self) {
     return BOOL2RB(result);
 }
 
+/* call-seq:
+ *   update_from(other) -> true or false
+ *
+ * Copies the contents of +other+ (a VertexBuffer of the same vertex count)
+ * into this buffer.
+ *
+ * @return [Boolean] whether the update succeeded
+ * @raise [TypeError] if +other+ is not a VertexBuffer
+ */
 static VALUE VertexBuffer_update_from(VALUE self, VALUE rb_other) {
     if (!rb_obj_is_kind_of(rb_other, rb_cVertexBuffer)) {
         raise_invalid_argument_class(rb_cVertexBuffer);
@@ -126,6 +171,14 @@ static VALUE VertexBuffer_update_from(VALUE self, VALUE rb_other) {
 
 /* Exchanges the two buffers' contents in place, so anything already holding
    either object sees the swap. */
+/* call-seq:
+ *   swap(other) -> self
+ *
+ * Swaps the contents with +other+.
+ *
+ * @return [self]
+ * @raise [TypeError] if +other+ is not a VertexBuffer
+ */
 static VALUE VertexBuffer_swap(VALUE self, VALUE rb_other) {
     if (!rb_obj_is_kind_of(rb_other, rb_cVertexBuffer)) {
         raise_invalid_argument_class(rb_cVertexBuffer);
@@ -136,38 +189,93 @@ static VALUE VertexBuffer_swap(VALUE self, VALUE rb_other) {
     return self;
 }
 
+/* call-seq: primitive -> Symbol
+ *
+ * Returns the primitive type used to draw the vertices.
+ *
+ * @return [Symbol] see VertexArray#primitive
+ */
 static VALUE VertexBuffer_get_primitive_type(VALUE self) {
     return ID2SYM(rb_intern(
         primitive_type_name(sfVertexBuffer_getPrimitiveType(Get_VertexBuffer_Struct(self)))));
 }
 
+/* call-seq:
+ *   primitive=(value) -> Symbol
+ *
+ * Sets the primitive type used to draw the vertices.
+ *
+ * @return [Symbol] +value+
+ */
 static VALUE VertexBuffer_set_primitive_type(VALUE self, VALUE rb_type) {
     sfVertexBuffer_setPrimitiveType(Get_VertexBuffer_Struct(self), primitive_type_from_rb(rb_type));
     return rb_type;
 }
 
+/* call-seq: usage -> Symbol
+ *
+ * Returns the buffer's usage hint.
+ *
+ * @return [Symbol] one of :stream, :dynamic, :static
+ */
 static VALUE VertexBuffer_get_usage(VALUE self) {
     return ID2SYM(rb_intern(usage_names[sfVertexBuffer_getUsage(Get_VertexBuffer_Struct(self))]));
 }
 
+/* call-seq:
+ *   usage=(value) -> Symbol
+ *
+ * Sets the buffer's usage hint.
+ *
+ * @return [Symbol] +value+
+ */
 static VALUE VertexBuffer_set_usage(VALUE self, VALUE rb_usage) {
     sfVertexBuffer_setUsage(Get_VertexBuffer_Struct(self), usage_from_rb(rb_usage));
     return rb_usage;
 }
 
+/* call-seq: native_handle -> Integer
+ *
+ * Returns the underlying OpenGL handle.
+ *
+ * @return [Integer] the underlying OpenGL buffer handle
+ */
 static VALUE VertexBuffer_get_native_handle(VALUE self) {
     return UINT2NUM(sfVertexBuffer_getNativeHandle(Get_VertexBuffer_Struct(self)));
 }
 
+/* call-seq: bind -> self
+ *
+ * Binds the buffer for drawing.
+ *
+ * @return [self]
+ */
 static VALUE VertexBuffer_bind(VALUE self) {
     sfVertexBuffer_bind(Get_VertexBuffer_Struct(self));
     return self;
 }
 
+/* call-seq:
+ *   VertexBuffer.available? -> true or false
+ *
+ * Returns +true+ if vertex buffers are supported.
+ *
+ * @return [Boolean] whether the system supports vertex buffers
+ */
 static VALUE VertexBuffer_is_available(VALUE klass) {
     return BOOL2RB(sfVertexBuffer_isAvailable());
 }
 
+/* call-seq:
+ *   draw(target, state) -> nil
+ *
+ * Part of the Drawable interface; call Target#draw instead of this
+ * directly.
+ *
+ * @return [nil]
+ * @raise [TypeError] if +target+ is not a Target or +state+ is not a
+ *   RenderState
+ */
 static VALUE VertexBuffer_draw(VALUE self, VALUE rb_target, VALUE rb_state) {
     if (!rb_obj_is_kind_of(rb_target, Get_Klass_Target())) {
         raise_invalid_argument_class(Get_Klass_Target());
@@ -184,8 +292,22 @@ static VALUE VertexBuffer_draw(VALUE self, VALUE rb_target, VALUE rb_state) {
     return Qnil;
 }
 
-void Init_VertexBuffer(VALUE rb_module) {
-    rb_cVertexBuffer = rb_define_class_under(rb_module, "VertexBuffer", rb_cObject);
+/* Document-class: SFML::VertexBuffer
+ * Like VertexArray, but the vertex data lives in GPU memory rather than
+ * being re-uploaded on every draw -- more efficient for large, static
+ * or semi-static vertex sets.
+ *
+ * Includes +Drawable+.
+ *
+ * @!attribute primitive
+ *   The primitive type used to draw the vertices.
+ *   @return [Symbol]
+ * @!attribute usage
+ *   The buffer's usage hint.
+ *   @return [Symbol] one of :stream, :dynamic, :static
+ */
+void Init_VertexBuffer(VALUE rb_mSFML) {
+    rb_cVertexBuffer = rb_define_class_under(rb_mSFML, "VertexBuffer", rb_cObject);
 
     rb_include_module(rb_cVertexBuffer, Get_Module_Drawable());
 

data/ext/graphics/view.c

@@ -42,12 +42,27 @@ static VALUE View_new_from(VALUE klass, sfView* c_view) {
     return self;
 }
 
+/* call-seq:
+ *   View.new -> View
+ *
+ * Creates a default view covering the (0, 0) - (1000, 1000) region.
+ *
+ * @return [View]
+ */
 static VALUE View_new(VALUE klass) {
     return View_new_from(klass, NULL);
 }
 
 /* The rect is the visible area: position is the top-left corner, not the
    centre, which is what distinguishes this from new + center=/size=. */
+/* call-seq:
+ *   View.from_rect(rect) -> View
+ *
+ * Creates a view covering the given rectangle.
+ *
+ * @return [View] a view whose visible area is +rect+ (position is the
+ *   top-left corner)
+ */
 static VALUE View_s_from_rect(VALUE klass, VALUE rb_rect) {
     return View_new_from(klass, sfView_createFromRect(rect_from_rb(rb_rect)));
 }
@@ -56,22 +71,51 @@ static VALUE View_init(VALUE self) {
     return self;
 }
 
+/* call-seq:
+ *   rotation=(value) -> self
+ *
+ * Sets the object's rotation, in degrees.
+ *
+ * @return [self]
+ */
 static VALUE View_set_rotation(VALUE self, VALUE rb_rotation) {
     sfView_setRotation(Get_View_Struct(self), NUM2DBL(rb_rotation));
     return self;
 }
 
+/* call-seq:
+ *   size=(value) -> self
+ *
+ * Sets the object's size.
+ *
+ * @return [self]
+ */
 static VALUE View_set_size(VALUE self, VALUE rb_scale) {
     sfView_setSize(Get_View_Struct(self), vec2f_from_rb(rb_scale));
     return self;
 }
 
+/* call-seq:
+ *   center=(value) -> self
+ *
+ * Sets the view's center.
+ *
+ * @return [self]
+ */
 static VALUE View_set_center(VALUE self, VALUE rb_origin) {
     sfVector2f origin = VEC2_RB2C(rb_origin);
     sfView_setCenter(Get_View_Struct(self), origin);
     return self;
 }
 
+/* call-seq:
+ *   viewport=(value) -> self
+ *
+ * Sets the viewport: the target-relative (0..1) rectangle this view is
+ * rendered into.
+ *
+ * @return [self]
+ */
 static VALUE View_set_viewport(VALUE self, VALUE rb_viewport) {
     sfFloatRect viewport = RECT_RB2C(rb_viewport);
     sfView_setViewport(Get_View_Struct(self), viewport);
@@ -79,55 +123,139 @@ static VALUE View_set_viewport(VALUE self, VALUE rb_viewport) {
     return self;
 }
 
+/* call-seq: rotation -> Float
+ *
+ * Returns the object's rotation, in degrees.
+ *
+ * @return [Float] degrees
+ */
 static VALUE View_get_rotation(VALUE self) {
     return DBL2NUM(sfView_getRotation(Get_View_Struct(self)));
 }
 
+/* call-seq: size -> Vector2
+ *
+ * Returns the object's size.
+ *
+ * @return [Vector2]
+ */
 static VALUE View_get_size(VALUE self) {
     return vec2f_to_rb(sfView_getSize(Get_View_Struct(self)));
 }
 
+/* call-seq: center -> Vector2
+ *
+ * Returns the view's center.
+ *
+ * @return [Vector2]
+ */
 static VALUE View_get_center(VALUE self) {
     return vec2f_to_rb(sfView_getCenter(Get_View_Struct(self)));
 }
 
+/* call-seq: viewport -> Rect
+ *
+ * Returns the target's viewport rectangle, or +nil+ if none is set.
+ *
+ * @return [Rect]
+ */
 static VALUE View_get_viewport(VALUE self) {
     return RECT_C2RB(sfView_getViewport(Get_View_Struct(self)));
 }
 
+/* call-seq:
+ *   scissor=(value) -> self
+ *
+ * Sets the target's scissor rectangle.
+ *
+ * @return [self]
+ */
 static VALUE View_set_scissor(VALUE self, VALUE rb_scissor) {
     sfView_setScissor(Get_View_Struct(self), RECT_RB2C(rb_scissor));
 
     return self;
 }
 
+/* call-seq: scissor -> Rect
+ *
+ * Returns the target's scissor rectangle, or +nil+ if none is set.
+ *
+ * @return [Rect]
+ */
 static VALUE View_get_scissor(VALUE self) {
     return RECT_C2RB(sfView_getScissor(Get_View_Struct(self)));
 }
 
+/* call-seq:
+ *   move(offset) -> self
+ *
+ * Moves the object by +offset+.
+ *
+ * @return [self]
+ */
 static VALUE View_move(VALUE self, VALUE rb_move) {
     sfView_move(Get_View_Struct(self), vec2f_from_rb(rb_move));
     return self;
 }
 
+/* call-seq:
+ *   rotate(angle) -> self
+ *
+ * Rotates the object by +angle+ degrees.
+ *
+ * @return [self]
+ */
 static VALUE View_rotate(VALUE self, VALUE rb_angle) {
     sfView_rotate(Get_View_Struct(self), NUM2DBL(rb_angle));
 
     return self;
 }
 
+/* call-seq:
+ *   zoom(factor) -> self
+ *
+ * Multiplies the view's size by +factor+.
+ *
+ * @return [self]
+ */
 static VALUE View_zoom(VALUE self, VALUE rb_zoom) {
     sfView_zoom(Get_View_Struct(self), NUM2DBL(rb_zoom));
 
     return self;
 }
 
+/* call-seq: copy -> View
+ *
+ * Returns a deep copy of the object.
+ *
+ * @return [View] an independent copy
+ */
 static VALUE View_copy(VALUE self) {
     return Get_Casting_View(sfView_copy(Get_View_Struct(self)));
 }
 
-void Init_View(VALUE rb_module) {
-    rb_cView = rb_define_class_under(rb_module, "View", rb_cObject);
+/* Document-class: SFML::View
+ * A 2D camera: the region of the scene visible on a render target, and
+ * where on that target it is shown.
+ *
+ * @!attribute rotation
+ *   The object's rotation, in degrees.
+ *   @return [Float] degrees
+ * @!attribute size
+ *   The object's size.
+ *   @return [Vector2]
+ * @!attribute center
+ *   The view's center.
+ *   @return [Vector2]
+ * @!attribute viewport
+ *   The view's viewport rectangle.
+ *   @return [Rect] the target-relative (0..1) rectangle this view renders into
+ * @!attribute scissor
+ *   The view's scissor rectangle.
+ *   @return [Rect]
+ */
+void Init_View(VALUE rb_mSFML) {
+    rb_cView = rb_define_class_under(rb_mSFML, "View", rb_cObject);
 
     rb_define_singleton_method(rb_cView, "new", View_new, 0);
     rb_define_singleton_method(rb_cView, "from_rect", View_s_from_rect, 1);