ruby-sdl2 0.1.0 → 0.2.0

data/gl.c.m4

@@ -27,15 +27,51 @@ static VALUE GLContext_new(SDL_GLContext context)
     c->context = context;
     return Data_Wrap_Struct(cGLContext, 0, GLContext_free, c);
 }
+
+/*
+ * Document-module: SDL2::GL
+ *
+ * This module provides the initialize/shutdown functions of OpenGL.
+ *
+ */
+
+/*
+ * Document-class: SDL2::GL::Context
+ *
+ * This class represents an OpenGL context.
+ *
+ * You must create a new OpenGL context before using
+ * OpenGL functions.
+ *
+ * @!method destroy?
+ *   Return true if the context is {#destroy destroyed}.
+ */
+
 /*
  * @overload create(window)
  *   Create an OpenGL context for use with an OpenGL window, and make it
  *   current.
  *
- *   @param window [SDL2::Window] the window corresponding with a new context
+ *   @param window [SDL2::Window] the window associate with a new context
  *   @return [SDL2::GL::Context]
  *
  *   @see #delete
+ *
+ *   @example
+ *
+ *     SDL2.init(SDL2::INIT_EVERYTHING)
+ *     # You need to create a window with `OPENGL' flag
+ *     window = SDL2::Window.create("testgl", 0, 0, WINDOW_W, WINDOW_H,
+ *                                  SDL2::Window::Flags::OPENGL)
+ *                                  
+ *     # Create a OpenGL context attached to the window
+ *     context = SDL2::GL::Context.create(window)
+ *
+ *     # You can use OpenGL functions
+ *          :
+ *          
+ *     # Delete the context after using OpenGL functions
+ *     context.destroy
  */
 static VALUE GLContext_s_create(VALUE self, VALUE window)
 {
@@ -46,6 +82,13 @@ static VALUE GLContext_s_create(VALUE self, VALUE window)
     return (current_context = GLContext_new(context));
 }
 
+/*
+ * Delete the OpenGL context.
+ *
+ * @return [nil]
+ *
+ * @see #destroy?
+ */
 static VALUE GLContext_destroy(VALUE self)
 {
     GLContext* c = Get_GLContext(self);
@@ -55,6 +98,13 @@ static VALUE GLContext_destroy(VALUE self)
     return Qnil;
 }
 
+/*
+ * @overload make_current(window)
+ *   Set the OpenGL context for rendering into an OpenGL window.
+ *
+ *   @param window [SDL2::Window] the window to associate with the context
+ *   @return [nil]
+ */
 static VALUE GLContext_make_current(VALUE self, VALUE window)
 {
     HANDLE_ERROR(SDL_GL_MakeCurrent(Get_SDL_Window(window), Get_SDL_GLContext(self)));
@@ -62,27 +112,71 @@ static VALUE GLContext_make_current(VALUE self, VALUE window)
     return Qnil;
 }
 
+/*
+ * Get the current OpenGL context.
+ *
+ * @return [SDL2::GL::Context] the curren context
+ * @return [nil] if there is no current context
+ *
+ * @see #make_current
+ */
 static VALUE GLContext_s_current(VALUE self)
 {
     return current_context;
 }
 
+/*
+ * @overload extension_supported?(extension) 
+ *   Return true if the current context supports **extension**
+ *
+ *   @param extension [String] the name of an extension
+ *   @example
+ *     SDL2::GL.extension_supported?("GL_EXT_framebuffer_blit")
+ */
 static VALUE GL_s_extension_supported_p(VALUE self, VALUE extension)
 {
     return INT2BOOL(SDL_GL_ExtensionSupported(StringValueCStr(extension)));
 }
 
+/*
+ * Get the state of swap interval of the current context.
+ *
+ * @return [Integer]
+ *   return 0 when vsync is not used,
+ *   return 1 when vsync is used,
+ *   and return -1 when vsync is not supported by the system (OS).
+ *   
+ */
 static VALUE GL_s_swap_interval(VALUE self)
 {
     return INT2NUM(SDL_GL_GetSwapInterval());
 }
 
+
+/*
+ * @overload swap_interval=(interval) 
+ *   Set the state of swap interval of the current context.
+ *
+ *   @param interval [Integer]
+ *     0 if you don't want to wait for vsync,
+ *     1 if you want to wait for vsync,
+ *     -1 if you want to use late swap tearing
+ *   @return [nil]
+ *   
+ */
 static VALUE GL_s_set_swap_interval(VALUE self, VALUE interval)
 {
     HANDLE_ERROR(SDL_GL_SetSwapInterval(NUM2INT(interval)));
     return Qnil;
 }
 
+/*
+ * @overload get_attribute(attr)
+ *   Get the acutal value for an attribute from current context.
+ *   
+ *   @param attr [Integer] the OpenGL attribute to query
+ *   @return [Integer] 
+ */
 static VALUE GL_s_get_attribute(VALUE self, VALUE attr)
 {
     int value;
@@ -90,6 +184,14 @@ static VALUE GL_s_get_attribute(VALUE self, VALUE attr)
     return INT2NUM(value);
 }
 
+/*
+ * @overload set_attribute(attr, value)
+ *   Set an OpenGL window attribute before window creation.
+ *   
+ *   @param attr [Integer] the OpenGL attribute to set
+ *   @param value [Integer] the desired value for the attribute
+ *   @return [value]
+ */
 static VALUE GL_s_set_attribute(VALUE self, VALUE attr, VALUE value)
 {
     HANDLE_ERROR(SDL_GL_SetAttribute(NUM2INT(attr), NUM2INT(value)));
@@ -113,7 +215,7 @@ void rubysdl2_init_gl(void)
     rb_define_module_function(mGL, "swap_interval=", GL_s_set_swap_interval, 1);
     rb_define_module_function(mGL, "get_attribute", GL_s_get_attribute, 1);
     rb_define_module_function(mGL, "set_attribute", GL_s_set_attribute, 2);
-    
+
     /* define(`DEFINE_GL_ATTR_CONST',`rb_define_const(mGL, "$1", INT2NUM(SDL_GL_$1))') */
     /* OpenGL attribute - minimal bits of red channel in color buffer, default is 3 */
     DEFINE_GL_ATTR_CONST(RED_SIZE);
@@ -161,21 +263,33 @@ void rubysdl2_init_gl(void)
     DEFINE_GL_ATTR_CONST(CONTEXT_MAJOR_VERSION);
     /* OpenGL attribute - OpenGL context minor version */
     DEFINE_GL_ATTR_CONST(CONTEXT_MINOR_VERSION);
-    /* OpenGL attribute - the bit combination of following constants, or 0.
-     * default is 0
+    /*
+     * INT2NUM(SDL_GL_CONTEXT_FLAGS):
      * 
+     * OpenGL attribute - the bit combination of following constants, or 0.
+     * default is 0
+     *
      * * {SDL2::GL::CONTEXT_DEBUG_FLAG}
      * * {SDL2::GL::CONTEXT_FORWARD_COMPATIBLE_FLAG}
      * * {SDL2::GL::CONTEXT_ROBUST_ACCESS_FLAG}
      * * {SDL2::GL::CONTEXT_RESET_ISOLATION_FLAG}
+     *
+     * These flags are mapped to some OpenGL extensions. Please see
+     * the documentation of each constant for more details.
+     *
+     * https://wiki.libsdl.org/SDL_GLcontextFlag
      */
     DEFINE_GL_ATTR_CONST(CONTEXT_FLAGS);
-    /* OpenGL attribute - type of GL context, one of the following constants,
+    /* INT2NUM(SDL_GL_CONTEXT_PROFILE_MASK):
+     *
+     * OpenGL attribute - type of GL context, one of the following constants,
      * defaults depends on platform
      *
-     * * {SDL2::GL::CONTEXT::PROFILE_CORE}
-     * * {SDL2::GL::CONTEXT::PROFILE_COMPATIBLITY}
-     * * {SDL2::GL::CONTEXT::PROFILE_ES}
+     * * {CONTEXT_PROFILE_CORE}
+     * * {CONTEXT_PROFILE_COMPATIBILITY}
+     * * {CONTEXT_PROFILE_ES}
+     *
+     * https://wiki.libsdl.org/SDL_GLprofile
      */
     DEFINE_GL_ATTR_CONST(CONTEXT_PROFILE_MASK);
     /* OpenGL attribute - OpenGL context sharing, default is 0 */
@@ -188,13 +302,49 @@ void rubysdl2_init_gl(void)
     DEFINE_GL_ATTR_CONST(CONTEXT_EGL);
 
     /* define(`DEFINE_GL_CONTEXT_CONST',`rb_define_const(mGL, "CONTEXT_$1", INT2NUM(SDL_GL_CONTEXT_$1))') */
+
+    /* This flag maps to GLX_CONTEXT_DEBUG_BIT_ARB in
+     * the GLX_ARB_create_context extension for X11
+     * and WGL_CONTEXT_DEBUG_BIT_ARB in the WGL_ARB_create_context
+     * extension for Windows.
+     */
     DEFINE_GL_CONTEXT_CONST(DEBUG_FLAG);
+    /*
+     * This flag maps to GLX_CONTEXT_FORWARD_COMPATIBLE_BIT_ARB in the
+     * GLX_ARB_create_context extension for X11 and
+     * WGL_CONTEXT_FORWARD_COMPATIBLE_BIT_ARB in the WGL_ARB_create_context
+     * extension for Windows.
+     */
     DEFINE_GL_CONTEXT_CONST(FORWARD_COMPATIBLE_FLAG);
+    /*
+     * This flag maps to GLX_CONTEXT_ROBUST_ACCESS_BIT_ARB in the
+     * GLX_ARB_create_context_robustness extension for X11 and
+     * WGL_CONTEXT_ROBUST_ACCESS_BIT_ARB in the WGL_ARB_create_context_robustness
+     * extension for Windows. 
+     */
     DEFINE_GL_CONTEXT_CONST(ROBUST_ACCESS_FLAG);
+    /*
+     * This flag maps to GLX_CONTEXT_RESET_ISOLATION_BIT_ARB in the
+     * GLX_ARB_robustness_isolation extension for X11 and
+     * WGL_CONTEXT_RESET_ISOLATION_BIT_ARB in the WGL_ARB_create_context_robustness
+     * extension for Windows.
+     */
     DEFINE_GL_CONTEXT_CONST(RESET_ISOLATION_FLAG);
-    
+
+    /*
+     * OpenGL core profile - deprecated
+     * functions are disabled
+     */
     DEFINE_GL_CONTEXT_CONST(PROFILE_CORE);
+    /*
+     * OpenGL compatibility profile -
+     * deprecated functions are allowed
+     */
     DEFINE_GL_CONTEXT_CONST(PROFILE_COMPATIBILITY);
+    /*
+     * OpenGL ES profile - only a subset of the
+     * base OpenGL functionality is available
+     */
     DEFINE_GL_CONTEXT_CONST(PROFILE_ES);
     
     rb_gc_register_address(&current_context);

data/hint.c

@@ -3,12 +3,33 @@
 
 static VALUE sym_priority;
 
+/*
+ * Document-module: SDL2::Hints
+ *
+ * This module enables you to get and set configuration hints.
+ *
+ */
+
+/*
+ * Clear all hints set by {.[]=}.
+ *
+ * @return [nil]
+ */
 static VALUE Hints_s_clear(VALUE self)
 {
     SDL_ClearHints();
     return Qnil;
 }
 
+/*
+ * @overload [](hint)
+ *   Get the value of a hint.
+ *
+ *   @param hint [String] the name of the hint to query
+ *   
+ * @return [String] the string value of a hint
+ * @return [nil] if the hint isn't set
+ */
 static VALUE Hints_s_aref(VALUE self, VALUE name)
 {
     const char* value = SDL_GetHint(StringValueCStr(name));
@@ -18,6 +39,29 @@ static VALUE Hints_s_aref(VALUE self, VALUE name)
         return Qnil;
 }
 
+/*
+ * Set the value of a hint.
+ * 
+ * @overload []=(hint, value)
+ *   Set a hint with normal priority.
+ *
+ *   @param hint [String] the name of the hint to query
+ *   @param value [String] the value of the hint varaible
+ *
+ * @overload []=(hint, priority: , value)
+ *   Set a hint with given priority.
+ *
+ *   @param hint [String] the name of the hint to query
+ *   @param priority [Integer] the priority, one of the
+ *     {DEFAULT}, {NORMAL}, or {OVERRIDE}.
+ *   @param value [String] the value of the hint varaible
+ *   
+ * @return [Boolean] return true if the hint was set
+ *
+ * @example
+ *   SDL2::Hints["SDL_HINT_XINPUT_ENABLED", priority: SDL2::Hints::OVERRIDE] = "0"
+ *
+ */
 static VALUE Hints_s_aset(int argc, VALUE* argv, VALUE self)
 {
     VALUE name, pri, value;
@@ -41,16 +85,15 @@ void rubysdl2_init_hints(void)
     VALUE mHints = rb_define_module_under(mSDL2, "Hints");
     
     rb_define_singleton_method(mHints, "clear", Hints_s_clear, 0);
-    rb_define_singleton_method(mHints, "[]", Hints_s_aref, 1);
     rb_define_singleton_method(mHints, "get", Hints_s_aref, 1);
     rb_define_singleton_method(mHints, "[]=", Hints_s_aset, -1);
-    rb_define_singleton_method(mHints, "set", Hints_s_aset, -1);
-    
-#define DEFINE_HINT_CONST(t) \
-    rb_define_const(mHints, #t, INT2NUM(SDL_HINT_##t))
-    DEFINE_HINT_CONST(DEFAULT);
-    DEFINE_HINT_CONST(NORMAL);
-    DEFINE_HINT_CONST(OVERRIDE);
+
+    /* low priority, used fro default values */
+    rb_define_const(mHints, "DEFAULT", INT2NUM(SDL_HINT_DEFAULT));
+    /* medium priority, overrided by an environment variable */
+    rb_define_const(mHints, "NORMAL", INT2NUM(SDL_HINT_NORMAL));
+    /* high priority, this priority overrides the value by environment variables */
+    rb_define_const(mHints, "OVERRIDE", INT2NUM(SDL_HINT_OVERRIDE));
 
     sym_priority = ID2SYM(rb_intern("priority"));
 }

data/key.c.m4

@@ -168,6 +168,12 @@ static VALUE Mod_s_set_state(VALUE self, VALUE keymod)
     return Qnil;
 }
 
+/*
+ * Document-module: SDL2::TextInput
+ *
+ * This module provides Unicode text input support.
+ *
+ */
 static VALUE TextInput_s_active_p(VALUE self)
 {
     return INT2BOOL(SDL_IsTextInputActive());

data/lib/sdl2/version.rb

@@ -1,6 +1,6 @@
 module SDL2
   # Version string of Ruby/SDL2
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
   # Version of Ruby/SDL2, [major, minor, patch level] 
-  VERSION_NUMBER = [0, 1, 0]
+  VERSION_NUMBER = [0, 2, 0]
 end

data/messagebox.c

@@ -4,6 +4,8 @@
 static VALUE sym_flags, sym_window, sym_title, sym_message, sym_buttons, sym_color_scheme,
     sym_id, sym_text, sym_bg, sym_button_border, sym_button_bg, sym_button_selected;
 
+static VALUE mMessageBox;
+
 static inline SDL_Window* Get_SDL_Window_or_NULL(VALUE win)
 {
     if (win == Qnil)
@@ -13,7 +15,13 @@ static inline SDL_Window* Get_SDL_Window_or_NULL(VALUE win)
 }
 
 /*
- * @overload show_simple_message_box(flag, title, message, parent)
+ * Document-module: SDL2::MessageBox
+ *
+ * This module provides functions to show a modal message box.
+ */
+
+/*
+ * @overload show_simple_box(flag, title, message, parent)
  *   Create a simple modal message box.
  *
  *   This function pauses all ruby's threads and
@@ -23,13 +31,13 @@ static inline SDL_Window* Get_SDL_Window_or_NULL(VALUE win)
  *   
  *   You specify one of the following constants as flag
  *
- *   * {SDL2::MESSAGEBOX_ERROR}
- *   * {SDL2::MESSAGEBOX_WARNING}
- *   * {SDL2::MESSAGEBOX_INFORMATION}
+ *   * {SDL2::MessageBox::ERROR}
+ *   * {SDL2::MessageBox::WARNING}
+ *   * {SDL2::MessageBox::INFORMATION}
  *
  *   @example show warning dialog
  *   
- *       SDL2.show_simple_message_box(SDL2::MESSAGEBOX_WARNING, "warning!",
+ *       SDL2.show_simple_message_box(SDL2::MessageBox::WARNING, "warning!",
  *                                    "Somewhat special warning message!!", nil)
  *                                
  *   @param [Integer] flag one of the above flags
@@ -40,8 +48,8 @@ static inline SDL_Window* Get_SDL_Window_or_NULL(VALUE win)
  *   
  *   @see .show_message_box
  */
-static VALUE SDL2_s_show_simple_message_box(VALUE self, VALUE flag, VALUE title,
-                                            VALUE message, VALUE parent)
+static VALUE MessageBox_s_show_simple_box(VALUE self, VALUE flag, VALUE title,
+                                          VALUE message, VALUE parent)
 {
     title = rb_str_export_to_utf8(title);
     message = rb_str_export_to_utf8(message);
@@ -62,19 +70,19 @@ static void set_color_scheme(VALUE colors, VALUE sym, SDL_MessageBoxColor* color
 }
 
 /*
- * @overload show_message_box(flag:, window: nil, title:, message:, buttons:, color_scheme: nil)
+ * @overload show(flag:, window: nil, title:, message:, buttons:, color_scheme: nil)
  *   Create a model message box.
  *
  *   You specify one of the following constants as flag
  *
- *   * {SDL2::MESSAGEBOX_ERROR}
- *   * {SDL2::MESSAGEBOX_WARNING}
- *   * {SDL2::MESSAGEBOX_INFORMATION}
+ *   * {SDL2::MessageBox::ERROR}
+ *   * {SDL2::MessageBox::WARNING}
+ *   * {SDL2::MessageBox::INFORMATION}
  *
  *   One button in the dialog represents a hash with folloing elements.
  *   
- *       { flags: 0, SDL2::MESSAGEBOX_BUTTON_ESCAPEKEY_DEFAULT, or
- *                SDL2::MESSAGEBOX_BUTTON_RETURNKEY_DEFAULT,
+ *       { flags: 0, SDL2::MessageBox::BUTTON_ESCAPEKEY_DEFAULT, or
+ *                SDL2::MessageBox::BUTTON_RETURNKEY_DEFAULT,
  *                you can ignore it for 0,
  *         text: text of a button,
  *         id: index of the button
@@ -95,7 +103,7 @@ static void set_color_scheme(VALUE colors, VALUE sym, SDL_MessageBoxColor* color
  *   You can create a message box before calling {SDL2.init}.
  *
  *   @example show a dialog with 3 buttons
- *       button = SDL2.show_message_box(flags: SDL2::MESSAGEBOX_WARNING,
+ *       button = SDL2::MessageBox.show(flags: SDL2::MessageBox::WARNING,
  *                                      window: nil,
  *                                      title: "Warning window",
  *                                      message: "Here is the warning message",
@@ -103,11 +111,11 @@ static void set_color_scheme(VALUE colors, VALUE sym, SDL_MessageBoxColor* color
  *                                                  id: 0, 
  *                                                  text: "No",
  *                                                 }, 
- *                                                 {flags: SDL2::MESSAGEBOX_BUTTON_RETURNKEY_DEFAULT,
+ *                                                 {flags: SDL2::MessageBox::BUTTON_RETURNKEY_DEFAULT,
  *                                                  id: 1,
  *                                                  text: "Yes",
  *                                                 },
- *                                                 {flags: SDL2::MESSAGEBOX_BUTTON_ESCAPEKEY_DEFAULT,
+ *                                                 {flags: SDL2::MessageBox::BUTTON_ESCAPEKEY_DEFAULT,
  *                                                  id: 2,
  *                                                  text: "Cancel",
  *                                                 },
@@ -132,7 +140,7 @@ static void set_color_scheme(VALUE colors, VALUE sym, SDL_MessageBoxColor* color
  *   
  *   @see .show_simple_message_box
  */
-static VALUE SDL2_s_show_message_box(VALUE self, VALUE params)
+static VALUE MessageBox_s_show(VALUE self, VALUE params)
 {
     SDL_MessageBoxData mb_data;
     VALUE title, message, texts, buttons, color_scheme;
@@ -192,28 +200,22 @@ static VALUE SDL2_s_show_message_box(VALUE self, VALUE params)
 
 void rubysdl2_init_messagebox(void)
 {
-    rb_define_singleton_method(mSDL2, "show_simple_message_box",
-                               SDL2_s_show_simple_message_box, 4);
-    rb_define_singleton_method(mSDL2, "show_message_box", SDL2_s_show_message_box, 1);
-    /* This flag means that the message box shows an error message in
-     * {SDL2.show_simple_message_box} and {SDL2.show_message_box}.
-     */
-    rb_define_const(mSDL2, "MESSAGEBOX_ERROR", INT2NUM(SDL_MESSAGEBOX_ERROR));
-    /* This flag means that the message box shows a warning message in
-     * {SDL2.show_simple_message_box} and {SDL2.show_message_box}.
-     */
-    rb_define_const(mSDL2, "MESSAGEBOX_WARNING", INT2NUM(SDL_MESSAGEBOX_WARNING));
-    /* This flag means that the message box shows an informational message in
-     * {SDL2.show_simple_message_box} and {SDL2.show_message_box}.
-     */
-    rb_define_const(mSDL2, "MESSAGEBOX_INFORMATION", INT2NUM(SDL_MESSAGEBOX_INFORMATION));
-    /* This flag represents the button is selected when return key is pressed in
-     * {SDL2.show_message_box}. */
-    rb_define_const(mSDL2, "MESSAGEBOX_BUTTON_RETURNKEY_DEFAULT",
+    mMessageBox = rb_define_module_under(mSDL2, "MessageBox");
+    
+    rb_define_singleton_method(mMessageBox, "show_simple_box",
+                               MessageBox_s_show_simple_box, 4);
+    rb_define_singleton_method(mMessageBox, "show", MessageBox_s_show, 1);
+    /* This flag means that the message box shows an error message */
+    rb_define_const(mMessageBox, "ERROR", INT2NUM(SDL_MESSAGEBOX_ERROR));
+    /* This flag means that the message box shows a warning message */
+    rb_define_const(mMessageBox, "WARNING", INT2NUM(SDL_MESSAGEBOX_WARNING));
+    /* This flag means that the message box shows an informational message */
+    rb_define_const(mMessageBox, "INFORMATION", INT2NUM(SDL_MESSAGEBOX_INFORMATION));
+    /* This flag represents the button is selected when return key is pressed */
+    rb_define_const(mMessageBox, "BUTTON_RETURNKEY_DEFAULT",
                     INT2NUM(SDL_MESSAGEBOX_BUTTON_RETURNKEY_DEFAULT));
-    /* This flag represents the button is selected when escape key is pressed in
-     * {SDL2.show_message_box}. */
-    rb_define_const(mSDL2, "MESSAGEBOX_BUTTON_ESCAPEKEY_DEFAULT",
+    /* This flag represents the button is selected when escape key is pressed */
+    rb_define_const(mMessageBox, "BUTTON_ESCAPEKEY_DEFAULT",
                     INT2NUM(SDL_MESSAGEBOX_BUTTON_ESCAPEKEY_DEFAULT));
 
     sym_flags = ID2SYM(rb_intern("flags"));