ruby-sdl2 0.1.0 → 0.2.0

data/video.c.m4

@@ -8,15 +8,24 @@
 #include <ruby/encoding.h>
 
 static VALUE cWindow;
+static VALUE mWindowFlags;
 static VALUE cDisplay;
 static VALUE cDisplayMode;
 static VALUE cRenderer;
+static VALUE mRendererFlags;
+static VALUE mBlendMode;
 static VALUE cTexture;
 static VALUE cRect;
 static VALUE cPoint;
 static VALUE cSurface;
 static VALUE cRendererInfo;
 static VALUE cPixelFormat; /* NOTE: This is related to SDL_PixelFormatEnum, not SDL_PixelFormat */
+static VALUE mPixelType;
+static VALUE mBitmapOrder;
+static VALUE mPackedOrder;
+static VALUE mArrayOrder;
+static VALUE mPackedLayout;
+
 static VALUE mScreenSaver;
 
 static VALUE hash_windowid_to_window = Qnil;
@@ -341,29 +350,6 @@ static VALUE SDL2_s_video_init(VALUE self, VALUE driver_name)
  * All of methods/class methods are available only after initializing video
  * subsystem by {SDL2.init}.
  *
- * # Window Flags
- *
- * OR'd bits of the following constants represents window states.
- * You can see a window state using {#flags} and create a window with a specified
- * state using flag parameter of {.create}.
- * 
- * * {SDL2::Window::FULLSCREEN} - fullscreen window
- * * {SDL2::Window::FULLSCREEN_DESKTOP} -
- *   fullscreen window at the current desktop resolution
- * * {SDL2::Window::OPENGL} - window usable with OpenGL context
- * * {SDL2::Window::SHOWN} - window is visible
- * * {SDL2::Window::HIDDEN} - window is not visible
- * * {SDL2::Window::BORDERLESS} - no window decoration
- * * {SDL2::Window::RESIZABLE} - window is resizable
- * * {SDL2::Window::MINIMIZDED} - window is minimized
- * * {SDL2::Window::MAXIMIZED} - window is maximized
- * * {SDL2::Window::INPUT_GRABBED} - window has grabbed input focus
- * * {SDL2::Window::INPUT_FOCUS} - window has input focus
- * * {SDL2::Window::MOUSE_FOCUS} - window has mouse focus
- * * {SDL2::Window::FOREIGN} - window is not created by SDL
- * * {SDL2::Window::ALLOW_HIGHDPI} - window should be created in high-DPI mode if supported
- * * {SDL2::Window::MOUSE_CAPTURE} - window has mouse captured
- *
  *
  * @!method destroy?
  *   Return true if the window is already destroyed.
@@ -377,7 +363,7 @@ static VALUE SDL2_s_video_init(VALUE self, VALUE driver_name)
  *   @param [Integer] y the y position of the left-top of the window
  *   @param [Integer] w the width of the window
  *   @param [Integer] h the height of the window
- *   @param [Integer] flags 0, or one or more [Window flag masks](#label-Flags) OR'd together
+ *   @param [Integer] flags 0, or one or more {Flags} OR'd together
  *   
  *   @return [SDL2::Window] created window
  *   
@@ -541,7 +527,7 @@ static VALUE Window_set_brightness(VALUE self, VALUE brightness)
 }
 
 /*
- * Get the [Window flag masks](#label-Window+Flags) of the window.
+ * Get the {SDL2::Window::Flags Window flag masks} of the window.
  *
  * @return [Integer] flags
  * @see .create
@@ -861,8 +847,8 @@ SIMPLE_WINDOW_METHOD(Restore, restore);
 /*
  * Get the fullscreen stete of the window
  *
- * @return [Integer] 0 for window mode, SDL2::Window::FULLSCREEN for 
- *   fullscreen mode, and SDL2::Window::FULLSCREEN_DESKTOP for fullscreen
+ * @return [Integer] 0 for window mode, {SDL2::Window::Flags::FULLSCREEN} for 
+ *   fullscreen mode, and {SDL2::Window::Flags::FULLSCREEN_DESKTOP} for fullscreen
  *   at the current desktop resolution.
  *
  * @see #fullscreen_mode=
@@ -878,8 +864,8 @@ static VALUE Window_fullscreen_mode(VALUE self)
  * @overload fullscreen_mode=(flag)
  *   Set the fullscreen state of the window
  *
- *   @param flag [Integer] 0 for window mode, SDL2::Window::FULLSCREEN for 
- *     fullscreen mode, and SDL2::Window::FULLSCREEN_DESKTOP for fullscreen
+ *   @param flag [Integer] 0 for window mode, {SDL2::Window::Flags::FULLSCREEN} for 
+ *     fullscreen mode, and {SDL2::Flags::Window::FULLSCREEN_DESKTOP} for fullscreen
  *     at the current desktop resolution.
  *   @return [flag]
  *   
@@ -891,13 +877,12 @@ static VALUE Window_set_fullscreen_mode(VALUE self, VALUE flags)
     return flags;
 }
 
-
+#if SDL_VERSION_ATLEAST(2,0,1)
 /*
  * Get the size of the drawable region.
  *
  * @return [[Integer, Integer]] the width and height of the region
  */
-#if SDL_VERSION_ATLEAST(2,0,1)
 static VALUE Window_gl_drawable_size(VALUE self)
 {
     int w, h;
@@ -947,6 +932,17 @@ static VALUE Window_debug_info(VALUE self)
     return info;
 }
 
+/*
+ * Document-module: SDL2::Window::Flags
+ *
+ * OR'd bits of the constants of this module represents window states.
+ * 
+ * You can see a window state using {SDL2::Window#flags}
+ * and create a window with a specified
+ * state using flag parameter of {SDL2::Window.create}.
+ *
+ */
+
 /*
  * Document-class: SDL2::Display
  *
@@ -955,7 +951,16 @@ static VALUE Window_debug_info(VALUE self)
  * This means that if you use dual screen, {.displays} returns two displays.
  *
  * This class handles color depth, resolution, and refresh rate of displays.
- * 
+ *
+ *
+ * @!attribute [r] index
+ *   The index of the display, 0 origin
+ *   @return [Integer]
+ *
+ * @!attribute [r] name
+ *   The name of the display
+ *   @return [Stirng]
+ *
  */
 
 /*
@@ -1077,6 +1082,7 @@ static Uint32 uint32_for_format(VALUE format)
  * An object of this class has information about color depth, refresh rate,
  * and resolution of a display.
  *
+ *
  */
 
 /*
@@ -1139,38 +1145,7 @@ static VALUE DisplayMode_refresh_rate(VALUE self)
  *
  * You can create a renderer using {SDL2::Window#create_renderer} and
  * use it to draw figures on the window.
- *
- * # Flags
- * You can specify the OR'd bits of the following constants
- * {SDL2::Window#create_renderer when you create a new renderer}.
- *
- * * SDL2::Renderer::SOFTWARE - the renderer is a software fallback
- * * SDL2::Renderer::ACCELERATED - the renderer uses hardware acceleration
- * * SDL2::Renderer::PRESENTVSYNC - present is synchronized with the refresh rate
- * * SDL2::Renderer::TARGETTEXTURE - the renderer supports rendering to texture
- *
- * No flags(==0) gives priority to available ACCELERATED renderers
- *
- * # Blending modes
- * You can use 4 types of blending mode for rendering graphics
- * using Renderer class.
- *
- * You can change the blending mode using
- * {#draw_blend_mode=} and {SDL2::Texture#blend_mode=}.
- * 
- * In the backend of SDL, opengl or direct3d blending
- * mechanism is used for blending operations.
- * 
- * * SDL2::BLENDMODE_NONE - no blending (dstRGBA = srcRGBA)
- * * SDL2::BLENDMODE_BLEND - alpha blending
- *     (dstRGB = (srcRGB * srcA) + (dstRGB * (1-srcA)),
- *      dstA = srcA + (dstA * (1-srcA)))
- * * SDL2::BLENDMODE_ADD - additive blending
- *      (dstRGB = (srcRGB * srcA) + dstRGB,
- *       dstA = dstA)
- * * SDL2::BLENDMODE_MUL - color modulate
- *      (dstRGB = srcRGB * dstRGB,
- *       dstA = dstA)
+ *      
  *
  * @!method destroy?
  *   Return true if the renderer is {#destroy destroyed}.
@@ -1215,9 +1190,9 @@ static VALUE Renderer_destroy(VALUE self)
  *
  *   You can use the following constants to specify access pattern
  *   
- *   * SDL2::Texture::ACCESS_STATIC - changes rarely, not lockable
- *   * SDL2::Texture::ACCESS_STREAMING - changes frequently, lockable
- *   * SDL2::Texture::ACCESS_TARGET - can be used as a render target
+ *   * {SDL2::Texture::ACCESS_STATIC}
+ *   * {SDL2::Texture::ACCESS_STREAMING}
+ *   * {SDL2::Texture::ACCESS_TARGET}
  *     
  *   @param [SDL2::PixelFormat,Integer] format format of the texture
  *   @param [Integer] access texture access pattern
@@ -1302,9 +1277,9 @@ static VALUE Renderer_copy(VALUE self, VALUE texture, VALUE srcrect, VALUE dstre
  *
  *   You can use the following constants to specify the horizontal/vertical flip:
  *   
- *   * SDL2::Renderer::FLIP_HORIZONTAL - flip horizontally
- *   * SDL2::Renderer::FLIP_VERTICAL - flip vertically
- *   * SDL2::Renderer::FLIP_NONE - do not flip, equal to zero
+ *   * {SDL2::Renderer::FLIP_HORIZONTAL} - flip horizontally
+ *   * {SDL2::Renderer::FLIP_VERTICAL} - flip vertically
+ *   * {SDL2::Renderer::FLIP_NONE} - do not flip, equal to zero
  *
  *   
  *   @param [SDL2::Texture] texture the source texture
@@ -1482,11 +1457,10 @@ static VALUE Renderer_info(VALUE self)
  * Get the blend mode used for drawing operations like
  * {#fill_rect} and {#draw_line}.
  *
- * For the blending modes, see [blending modes](#label-Blending+modes)
- *
  * @return [Integer]
  * 
  * @see #draw_blend_mode=
+ * @see SDL2::BlendMode
  */
 static VALUE Renderer_draw_blend_mode(VALUE self)
 {
@@ -1511,7 +1485,7 @@ static VALUE Renderer_draw_blend_mode(VALUE self)
  *   @return mode
  *
  *   @see #draw_blend_mode
- *
+ *   @see SDL2::BlendMode
  */
 static VALUE Renderer_set_draw_blend_mode(VALUE self, VALUE mode)
 {
@@ -1523,7 +1497,7 @@ static VALUE Renderer_set_draw_blend_mode(VALUE self, VALUE mode)
  * Get the clip rectangle for the current target.
  *
  * @return [SDL2::Rect] the current clip rectangle
- * 
+ * @see {#clip_rect=}
  */
 static VALUE Renderer_clip_rect(VALUE self)
 {
@@ -1532,13 +1506,38 @@ static VALUE Renderer_clip_rect(VALUE self)
     return rect;
 }
 
+/*
+ * @overload clip_rect=(rect)
+ *
+ *   Set the clip rectangle for the current target.
+ *
+ *   @return [rect]
+ *   @see #clip_rect
+ */
+static VALUE Renderer_set_clip_rect(VALUE self, VALUE rect)
+{
+    HANDLE_ERROR(SDL_RenderSetClipRect(Get_SDL_Renderer(self), Get_SDL_Rect(rect)));
+    return rect;
+}
+
 #if SDL_VERSION_ATLEAST(2,0,4)
+/*
+ * Get whether clipping is enabled on the renderer.
+ *
+ * @note This method is available since SDL 2.0.4.
+ */
 static VALUE Render_clip_enabled_p(VALUE self)
 {
     return INT2BOOL(SDL_RenderIsClipEnabled(Get_SDL_Renderer(self)));
 }
 #endif
 
+/*
+ * Get device indepndent resolution for rendering.
+ *
+ * @return [[Integer, Integer]] the logical width and height
+ * @see #logical_size=
+ */
 static VALUE Renderer_logical_size(VALUE self)
 {
     int w, h;
@@ -1546,6 +1545,29 @@ static VALUE Renderer_logical_size(VALUE self)
     return rb_ary_new3(2, INT2FIX(w), INT2FIX(h));
 }
 
+/*
+ * @overload logical_size=(w_and_h)
+ *
+ *   Set a device indepndent resolution for rendering.
+ *   
+ *   @param w_and_h [[Integer, Integer]] the width and height of the logical resolution
+ *   @return [w_and_h]
+ *   @see #logical_size
+ */
+static VALUE Renderer_set_logical_size(VALUE self, VALUE wh)
+{
+    HANDLE_ERROR(SDL_RenderSetLogicalSize(Get_SDL_Renderer(self),
+                                          NUM2DBL(rb_ary_entry(wh, 0)),
+                                          NUM2DBL(rb_ary_entry(wh, 1))));
+    return wh;
+}
+
+/*
+ * Get the drawing scale for the current target.
+ *
+ * @return [[Integer, Integer]] horizontal and vertical scale factor
+ * @see #scale=
+ */
 static VALUE Renderer_scale(VALUE self)
 {
     float scaleX, scaleY;
@@ -1553,6 +1575,37 @@ static VALUE Renderer_scale(VALUE self)
     return rb_ary_new3(2, DBL2NUM(scaleX), DBL2NUM(scaleY));
 }
 
+/*
+ * @overload scale=(scaleX_and_scaleY)
+ *
+ *   Set the drawing scale for rendering.
+ *
+ *   The drawing coordinates are scaled by the x/y scaling factors before they are used by the renderer.
+ *   This allows resolution independent drawing with a single coordinate system.
+ *   
+ *   If this results in scaling or subpixel drawing by the rendering backend,
+ *   it will be handled using the appropriate
+ *   quality hints. For best results use integer scaling factors.
+ *
+ *   @param scaleX_and_scaleY [[Float, Float]] the horizontal and vertical scaling factors
+ *   @return [scaleX_and_scaleY]
+ *   @see #scale
+ */
+static VALUE Renderer_set_scale(VALUE self, VALUE xy)
+{
+    float scaleX, scaleY;
+    scaleX = NUM2DBL(rb_ary_entry(xy, 0));
+    scaleY = NUM2DBL(rb_ary_entry(xy, 1));
+    HANDLE_ERROR(SDL_RenderSetScale(Get_SDL_Renderer(self), scaleX, scaleY));
+    return xy;
+}
+
+/*
+ * Get the drawing area for the current target.
+ *
+ * @return [SDL2::Rect] the current drawing area
+ * @see #viewport=
+ */
 static VALUE Renderer_viewport(VALUE self)
 {
     VALUE rect = rb_obj_alloc(cRect);
@@ -1560,6 +1613,20 @@ static VALUE Renderer_viewport(VALUE self)
     return rect;
 }
 
+/*
+ * @overload viewport=(area) 
+ *   Set the drawing area for rendering on the current target.
+ *
+ *   @param area [SDL2::Rect,nil] the drawing area, or nil to set the viewport to the entire target
+ *   @return [area]
+ *   @see #viewport
+ */
+static VALUE Renderer_set_viewport(VALUE self, VALUE rect)
+{
+    HANDLE_ERROR(SDL_RenderSetClipRect(Get_SDL_Renderer(self), Get_SDL_Rect_or_NULL(rect)));
+    return rect;
+}
+
 /*
  * Return true if the renderer supports render target.
  *
@@ -1570,6 +1637,11 @@ static VALUE Renderer_support_render_target_p(VALUE self)
     return INT2BOOL(SDL_RenderTargetSupported(Get_SDL_Renderer(self)));
 }
 
+/*
+ * Get the output size of a rendering context.
+ *
+ * @return [[Integer, Integer]] the width and the height
+ */
 static VALUE Renderer_output_size(VALUE self)
 {
     int w, h;
@@ -1586,7 +1658,7 @@ static VALUE Renderer_output_size(VALUE self)
  *  {#support_render_target?}.
  *  
  *  The target texture musbe be {#create_texture created} with the
- *  SDL2::Texture::ACCESS_TARGET flag.
+ *  {SDL2::Texture::ACCESS_TARGET} flag.
  *  
  *  @param [SDL2::Texture,nil] target the targeted texture, or nil
  *    for the default render target(i.e. screen)
@@ -1646,6 +1718,48 @@ static VALUE Renderer_debug_info(VALUE self)
     return info;
 }
 
+/*
+ * Document-class: SDL2::Renderer::Info
+ *
+ * This class contains information of a rendering context.
+ *
+ * @!attribute [r] name
+ *   @return [String] the name of the renderer
+ *
+ * @!attribute [r] texture_formats
+ *   @return [Array<SDL2::PixelFormat>] available texture formats
+ *
+ * @!attribute [r] max_texture_width
+ *   @return [Integer] maximum texture width
+ *   
+ * @!attribute [r] max_texture_height
+ *   @return [Integer] maximum texture height
+ */
+
+/*
+ * Document-module: SDL2::Renderer::Flags
+ *
+ * The OR'd bits of the constants of this module represents
+ * the state of renderers.
+ * 
+ * You can use this flag
+ * {SDL2::Window#create_renderer when you create a new renderer}.
+ * No flags(==0) gives priority to available ACCELERATED renderers.
+ */
+
+/*
+ * Document-module: SDL2::BlendMode
+ *
+ * Constants represent blend mode for {SDL2::Renderer.copy} and
+ * drawing operations.
+ *
+ * You can change the blending mode using
+ * {SDL2::Renderer#draw_blend_mode=} and {SDL2::Texture#blend_mode=}.
+ *
+ * In the backend of SDL, opengl or direct3d blending
+ * mechanism is used for blending operations.
+ */
+
 /*
  * Document-class: SDL2::Texture
  *
@@ -1772,9 +1886,9 @@ static VALUE Texture_format(VALUE self)
  *
  * The return value is one of the following:
  * 
- * * SDL2::Texture::ACCESS_STATIC - changes rarely, not lockable
- * * SDL2::Texture::ACCESS_STREAMING - changes frequently, lockable
- * * SDL2::Texture::ACCESS_TARGET - can be used as a render target
+ * * {SDL2::Texture::ACCESS_STATIC}
+ * * {SDL2::Texture::ACCESS_STREAMING}
+ * * {SDL2::Texture::ACCESS_TARGET}
  *
  * @return [Integer]
  * 
@@ -2244,11 +2358,23 @@ static VALUE Surface_s_blit(VALUE self, VALUE src, VALUE srcrect, VALUE dst, VAL
 }
 
 /*
+ * Create an empty RGB surface.
+ *
+ * If rmask, gmask, bmask are omitted, the default masks are used.
+ * If amask is omitted, alpha mask is considered to be zero.
+ *
  * @overload new(width, height, depth)
  * @overload new(width, height, depth, amask)
  * @overload new(width, heigth, depth, rmask, gmask, bmask, amask)
  *
- * @param width [Integer] 
+ * @param width [Integer] the width of the new surface
+ * @param height [Integer] the height of the new surface
+ * @param depth [Integer] the bit depth of the new surface
+ * @param rmask [Integer] the red mask of a pixel
+ * @param gmask [Integer] the green mask of a pixel
+ * @param bmask [Integer] the blue mask of a pixel
+ * @param amask [Integer] the alpha mask of a pixel
+ * 
  * @return [SDL2::Surface]
  */
 static VALUE Surface_s_new(int argc, VALUE* argv, VALUE self)
@@ -2464,32 +2590,109 @@ static VALUE Point_inspect(VALUE self)
 FIELD_ACCESSOR(Point, SDL_Point, x);
 FIELD_ACCESSOR(Point, SDL_Point, y);
 
+
+/*
+ * Document-class: SDL2::PixelFormat
+ *
+ * This class represents pixel format of textures, windows, and displays.
+ *
+ * In C level, SDL use unsigned integers as pixel formats. This class
+ * wraps these integers. You can get the integers from {#format}.
+ *
+ * @!attribute [r] format
+ *    An integer representing the pixel format.
+ *
+ *    @return [Integer]
+ */
+
+/*
+ * @overload initialze(format)
+ *
+ *   Initialize pixel format from the given integer representing a fomrmat.
+ *   
+ *   @param format [Integer] an unsigned integer as a pixel formats
+ */
 static VALUE PixelForamt_initialize(VALUE self, VALUE format)
 {
     rb_iv_set(self, "@format", format);
     return Qnil;
 }
 
+/*
+ * Get the type of the format.
+ *
+ * @return [Integer] One of the constants of {Type} module.
+ */
 static VALUE PixelFormat_type(VALUE self)
 {
     return UINT2NUM(SDL_PIXELTYPE(NUM2UINT(rb_iv_get(self, "@format"))));
 }
 
-#define PIXELFORMAT_ATTR_READER(field, extractor, c2ruby)               \
-    static VALUE PixelFormat_##field(VALUE self)                        \
-    {                                                                   \
-        return c2ruby(extractor(NUM2UINT(rb_iv_get(self, "@format")))); \
-    }
+/*
+define(`PIXELFORMAT_ATTR_READER',
+`static VALUE PixelFormat_$1(VALUE self)
+{
+    return $3($2(NUM2UINT(rb_iv_get(self, "@format"))));
+}')
+ */
 
+/*
+ * Get the human readable name of the pixel format
+ * 
+ * @return [String]
+ */
 PIXELFORMAT_ATTR_READER(name, SDL_GetPixelFormatName, utf8str_new_cstr);
+
+/*
+ * Get the ordering of channels or bits in the pixel format.
+ *
+ * @return [Integer] One of the constants of {BitmapOrder} module or {PackedOrder} module.
+ */
 PIXELFORMAT_ATTR_READER(order,  SDL_PIXELORDER, UINT2NUM);
+
+/*
+ * Get the channel bit pattern of the pixel format.
+ *
+ * @return [Integer] One of the constants of {PackedLayout} module.
+ */
 PIXELFORMAT_ATTR_READER(layout,  SDL_PIXELLAYOUT, UINT2NUM);
+
+/*
+ * Get the number of bits per pixel.
+ *
+ * @return [Integer]
+ */
 PIXELFORMAT_ATTR_READER(bits_per_pixel,  SDL_BITSPERPIXEL, INT2NUM);
+
+/*
+ * Get the number of bytes per pixel.
+ *
+ * @return [Integer]
+ */
 PIXELFORMAT_ATTR_READER(bytes_per_pixel,  SDL_BYTESPERPIXEL, INT2NUM);
+
+/*
+ * Return true if the pixel format have a palette.
+ */
 PIXELFORMAT_ATTR_READER(indexed_p,  SDL_ISPIXELFORMAT_INDEXED, INT2BOOL);
+
+/*
+ * Return true if the pixel format have an alpha channel.
+ */
 PIXELFORMAT_ATTR_READER(alpha_p,  SDL_ISPIXELFORMAT_ALPHA, INT2BOOL);
+
+/*
+ * Return true if the pixel format is not indexed, and not RGB(A),
+ * for example, the pixel format is YUV.
+ */
 PIXELFORMAT_ATTR_READER(fourcc_p,  SDL_ISPIXELFORMAT_FOURCC, INT2BOOL);
 
+/* 
+ * @overload ==(other)
+ *   Return true if two pixel format is the same format.
+ *
+ * @return [Boolean]
+ */
 static VALUE PixelFormat_eq(VALUE self, VALUE other)
 {
     if (!rb_obj_is_kind_of(other, cPixelFormat))
@@ -2498,6 +2701,7 @@ static VALUE PixelFormat_eq(VALUE self, VALUE other)
     return INT2BOOL(rb_iv_get(self, "@format") == rb_iv_get(other, "@format"));
 }
 
+/* @return [String] inspection string */
 static VALUE PixelFormat_inspect(VALUE self)
 {
     Uint32 format = NUM2UINT(rb_iv_get(self, "@format"));
@@ -2512,18 +2716,44 @@ static VALUE PixelFormat_inspect(VALUE self)
                       INT2BOOLCSTR(SDL_ISPIXELFORMAT_FOURCC(format)));
 }
 
+/*
+ * Document-module: SDL2::ScreenSaver
+ *
+ * This module provides functions to disable and enable a screensaver.
+ */
+
+/*
+ * Enable screensaver.
+ *
+ * @return [nil]
+ * @see .disable
+ * @see .enabled?
+ */
 static VALUE ScreenSaver_enable(VALUE self)
 {
     SDL_EnableScreenSaver();
     return Qnil;
 }
 
+/*
+ * Disable screensaver.
+ *
+ * @return [nil]
+ * @see .enable
+ * @see .enabled?
+ */
 static VALUE ScreenSaver_disable(VALUE self)
 {
     SDL_DisableScreenSaver();
     return Qnil;
 }
 
+/*
+ * Return true if the screensaver is enabled.
+ *
+ * @see .enable
+ * @see .disable
+ */
 static VALUE ScreenSaver_enabled_p(VALUE self)
 {
     return INT2BOOL(SDL_IsScreenSaverEnabled());
@@ -2579,27 +2809,48 @@ void rubysdl2_init_video(void)
     rb_define_method(cWindow, "gl_drawable_size", Window_gl_drawable_size, 0);
 #endif
     rb_define_method(cWindow, "gl_swap", Window_gl_swap, 0);
+
+    /* Indicate that you don't care what the window position is */
     rb_define_const(cWindow, "POS_CENTERED", INT2NUM(SDL_WINDOWPOS_CENTERED));
+    /* Indicate that the window position should be centered */
     rb_define_const(cWindow, "POS_UNDEFINED", INT2NUM(SDL_WINDOWPOS_UNDEFINED));
-#define DEFINE_SDL_WINDOW_FLAGS_CONST(n)                        \
-    rb_define_const(cWindow, #n, UINT2NUM(SDL_WINDOW_##n));
-    DEFINE_SDL_WINDOW_FLAGS_CONST(FULLSCREEN);
-    DEFINE_SDL_WINDOW_FLAGS_CONST(FULLSCREEN_DESKTOP);
-    DEFINE_SDL_WINDOW_FLAGS_CONST(OPENGL);
-    DEFINE_SDL_WINDOW_FLAGS_CONST(SHOWN);
-    DEFINE_SDL_WINDOW_FLAGS_CONST(HIDDEN);
-    DEFINE_SDL_WINDOW_FLAGS_CONST(BORDERLESS);
-    DEFINE_SDL_WINDOW_FLAGS_CONST(RESIZABLE);
-    DEFINE_SDL_WINDOW_FLAGS_CONST(MINIMIZED);
-    DEFINE_SDL_WINDOW_FLAGS_CONST(MAXIMIZED);
-    DEFINE_SDL_WINDOW_FLAGS_CONST(INPUT_GRABBED);
-    DEFINE_SDL_WINDOW_FLAGS_CONST(INPUT_FOCUS);
-    DEFINE_SDL_WINDOW_FLAGS_CONST(MOUSE_FOCUS);
-    DEFINE_SDL_WINDOW_FLAGS_CONST(FOREIGN);
+
+    mWindowFlags = rb_define_module_under(cWindow, "Flags");
+    /* define(`DEFINE_WINDOW_FLAGS_CONST',`rb_define_const(mWindowFlags, "$1", UINT2NUM(SDL_WINDOW_$1))') */
+    /* fullscreen window */ 
+    DEFINE_WINDOW_FLAGS_CONST(FULLSCREEN);
+    /* fullscreen window at the current desktop resolution */
+    DEFINE_WINDOW_FLAGS_CONST(FULLSCREEN_DESKTOP);
+    /* window usable with OpenGL context */ 
+    DEFINE_WINDOW_FLAGS_CONST(OPENGL);
+    /* window is visible */
+    DEFINE_WINDOW_FLAGS_CONST(SHOWN);
+    /* window is not visible */
+    DEFINE_WINDOW_FLAGS_CONST(HIDDEN);
+    /* no window decoration */
+    DEFINE_WINDOW_FLAGS_CONST(BORDERLESS);
+    /* window is resizable */ 
+    DEFINE_WINDOW_FLAGS_CONST(RESIZABLE);
+    /* window is minimized */
+    DEFINE_WINDOW_FLAGS_CONST(MINIMIZED);
+    /* window is maximized */
+    DEFINE_WINDOW_FLAGS_CONST(MAXIMIZED);
+    /* window has grabbed input focus */
+    DEFINE_WINDOW_FLAGS_CONST(INPUT_GRABBED);
+    /* window has input focus */
+    DEFINE_WINDOW_FLAGS_CONST(INPUT_FOCUS);
+    /* window has mouse focus */
+    DEFINE_WINDOW_FLAGS_CONST(MOUSE_FOCUS);
+    /* window is not created by SDL */
+    DEFINE_WINDOW_FLAGS_CONST(FOREIGN);
 #ifdef SDL_WINDOW_ALLOW_HIGHDPI
-    DEFINE_SDL_WINDOW_FLAGS_CONST(ALLOW_HIGHDPI);
+    /* window should be created in high-DPI mode if supported (>= SDL 2.0.1)*/
+    DEFINE_WINDOW_FLAGS_CONST(ALLOW_HIGHDPI);
+#endif
+#ifdef SDL_WINDOW_MOSUE_CAPTURE
+    /* window has mouse caputred (>= SDL 2.0.4) */
+    DEFINE_WINDOW_FLAGS_CONST(MOUSE_CAPTURE);
 #endif
-
 
     cDisplay = rb_define_class_under(mSDL2, "Display", rb_cObject);
     
@@ -2611,6 +2862,7 @@ void rubysdl2_init_video(void)
     rb_define_method(cDisplay, "desktop_mode", Display_desktop_mode, 0);
     rb_define_method(cDisplay, "closest_mode", Display_closest_mode, 1);
     rb_define_method(cDisplay, "bounds", Display_bounds, 0);
+
     
     cDisplayMode = rb_define_class_under(cDisplay, "Mode", rb_cObject);
 
@@ -2621,7 +2873,7 @@ void rubysdl2_init_video(void)
     rb_define_method(cDisplayMode, "w", DisplayMode_w, 0);
     rb_define_method(cDisplayMode, "h", DisplayMode_h, 0);
     rb_define_method(cDisplayMode, "refresh_rate", DisplayMode_refresh_rate, 0);
-    /* attr format, w, h, refresh_rate */
+    
     
     cRenderer = rb_define_class_under(mSDL2, "Renderer", rb_cObject);
     
@@ -2645,12 +2897,16 @@ void rubysdl2_init_video(void)
     rb_define_method(cRenderer, "draw_blend_mode", Renderer_draw_blend_mode, 0);
     rb_define_method(cRenderer, "draw_blend_mode=", Renderer_set_draw_blend_mode, 1);
     rb_define_method(cRenderer, "clip_rect", Renderer_clip_rect, 0);
+    rb_define_method(cRenderer, "clip_rect=", Renderer_set_clip_rect, 1);
 #if SDL_VERSION_ATLEAST(2,0,4)
     rb_define_method(cRenderer, "clip_enabled?", Render_clip_enabled_p, 0);
 #endif
     rb_define_method(cRenderer, "logical_size", Renderer_logical_size, 0);
+    rb_define_method(cRenderer, "logical_size=", Renderer_set_logical_size, 1);
     rb_define_method(cRenderer, "scale", Renderer_scale, 0);
+    rb_define_method(cRenderer, "scale=", Renderer_set_scale, 1);
     rb_define_method(cRenderer, "viewport", Renderer_viewport, 0);
+    rb_define_method(cRenderer, "viewport=", Renderer_set_viewport, 1);
     rb_define_method(cRenderer, "support_render_target?", Renderer_support_render_target_p, 0);
     rb_define_method(cRenderer, "output_size", Renderer_output_size, 0);
     rb_define_method(cRenderer, "render_target", Renderer_render_target, 0);
@@ -2658,24 +2914,37 @@ void rubysdl2_init_video(void)
     rb_define_method(cRenderer, "reset_render_target", Renderer_reset_render_target, 0);
     
     rb_define_method(cRenderer, "info", Renderer_info, 0);
-#define DEFINE_SDL_RENDERER_FLAGS_CONST(n)                      \
-    rb_define_const(cRenderer, #n, UINT2NUM(SDL_RENDERER_##n))
-    DEFINE_SDL_RENDERER_FLAGS_CONST(SOFTWARE);
-    DEFINE_SDL_RENDERER_FLAGS_CONST(ACCELERATED);
+
+    mRendererFlags = rb_define_module_under(cRenderer, "Flags");
+    
+    /* define(`DEFINE_RENDERER_FLAGS_CONST',`rb_define_const(mRendererFlags, "$1", UINT2NUM(SDL_RENDERER_$1))') */
+    /* the renderer is a software fallback */
+    DEFINE_RENDERER_FLAGS_CONST(SOFTWARE);
+    /* the renderer uses hardware acceleration */
+    DEFINE_RENDERER_FLAGS_CONST(ACCELERATED);
 #ifdef SDL_RENDERER_PRESENTVSYNC
-    DEFINE_SDL_RENDERER_FLAGS_CONST(PRESENTVSYNC);
+    /* present is synchronized with the refresh rate */
+    DEFINE_RENDERER_FLAGS_CONST(PRESENTVSYNC);
 #endif
-    DEFINE_SDL_RENDERER_FLAGS_CONST(TARGETTEXTURE);
-#define DEFINE_SDL_FLIP_CONST(t)                                        \
-    rb_define_const(cRenderer, "FLIP_" #t, INT2FIX(SDL_FLIP_##t))
+    /* the renderer supports rendering to texture */ 
+    DEFINE_RENDERER_FLAGS_CONST(TARGETTEXTURE);
+    /* define(`DEFINE_SDL_FLIP_CONST',`rb_define_const(cRenderer, "FLIP_$1", INT2FIX(SDL_FLIP_$1))') */
+    /* Do not flip, used in {Renderer#copy_ex} */
     DEFINE_SDL_FLIP_CONST(NONE);
+    /* Flip horizontally, used in {Renderer#copy_ex} */
     DEFINE_SDL_FLIP_CONST(HORIZONTAL);
+    /* Flip vertically, used in {Renderer#copy_ex} */
     DEFINE_SDL_FLIP_CONST(VERTICAL);
-#define DEFINE_BLENDMODE_CONST(t)                                       \
-    rb_define_const(mSDL2, "BLENDMODE_" #t, INT2FIX(SDL_BLENDMODE_##t))
+    
+    mBlendMode = rb_define_module_under(mSDL2, "BlendMode");
+    /* define(`DEFINE_BLENDMODE_CONST',`rb_define_const(mBlendMode, "$1", INT2FIX(SDL_BLENDMODE_$1))') */
+    /* no blending (dstRGBA = srcRGBA) */
     DEFINE_BLENDMODE_CONST(NONE);
+    /* alpha blending (dstRGB = (srcRGB * srcA) + (dstRGB * (1-srcA), dstA = srcA + (dstA * (1-srcA)))*/
     DEFINE_BLENDMODE_CONST(BLEND);
+    /* additive blending (dstRGB = (srcRGB * srcA) + dstRGB, dstA = dstA) */
     DEFINE_BLENDMODE_CONST(ADD);
+    /* color modulate (multiplicative) (dstRGB = srcRGB * dstRGB, dstA = dstA) */
     DEFINE_BLENDMODE_CONST(MOD);
     
     cTexture = rb_define_class_under(mSDL2, "Texture", rb_cObject);
@@ -2692,10 +2961,12 @@ void rubysdl2_init_video(void)
     rb_define_method(cTexture, "h", Texture_h, 0);
     rb_define_method(cTexture, "inspect", Texture_inspect, 0);
     rb_define_method(cTexture, "debug_info", Texture_debug_info, 0);
-#define DEFINE_TEXTUREAH_ACCESS_CONST(t)                                \
-    rb_define_const(cTexture, "ACCESS_" #t, INT2NUM(SDL_TEXTUREACCESS_##t))
+    /* define(`DEFINE_TEXTUREAH_ACCESS_CONST', `rb_define_const(cTexture, "ACCESS_$1", INT2NUM(SDL_TEXTUREACCESS_$1))') */
+    /* texture access pattern - changes rarely, not lockable */
     DEFINE_TEXTUREAH_ACCESS_CONST(STATIC);
+    /* texture access pattern - changes frequently, lockable */
     DEFINE_TEXTUREAH_ACCESS_CONST(STREAMING);
+    /* texture access pattern - can be used as a render target */
     DEFINE_TEXTUREAH_ACCESS_CONST(TARGET);
 
     
@@ -2768,17 +3039,74 @@ void rubysdl2_init_video(void)
     rb_define_method(cPixelFormat, "alpha?", PixelFormat_alpha_p, 0);
     rb_define_method(cPixelFormat, "fourcc?", PixelFormat_fourcc_p, 0);
     rb_define_method(cPixelFormat, "==", PixelFormat_eq, 1);
+
+    mPixelType = rb_define_module_under(cPixelFormat, "Type");
+    /* define(`DEFINE_PIXELTYPE_CONST',`rb_define_const(mPixelType, "$1", UINT2NUM(SDL_PIXELTYPE_$1))') */
+    DEFINE_PIXELTYPE_CONST(UNKNOWN);
+    DEFINE_PIXELTYPE_CONST(INDEX1);
+    DEFINE_PIXELTYPE_CONST(INDEX4);
+    DEFINE_PIXELTYPE_CONST(INDEX8);
+    DEFINE_PIXELTYPE_CONST(PACKED8);
+    DEFINE_PIXELTYPE_CONST(PACKED16);
+    DEFINE_PIXELTYPE_CONST(PACKED32);
+    DEFINE_PIXELTYPE_CONST(ARRAYU8);
+    DEFINE_PIXELTYPE_CONST(ARRAYU16);
+    DEFINE_PIXELTYPE_CONST(ARRAYU32);
+    DEFINE_PIXELTYPE_CONST(ARRAYF16);
+    DEFINE_PIXELTYPE_CONST(ARRAYF32);
+
+    mBitmapOrder = rb_define_module_under(cPixelFormat, "BitmapOrder");
+    rb_define_const(mBitmapOrder, "NONE", UINT2NUM(SDL_BITMAPORDER_NONE));
+    rb_define_const(mBitmapOrder, "O_1234", UINT2NUM(SDL_BITMAPORDER_1234));
+    rb_define_const(mBitmapOrder, "O_4321", UINT2NUM(SDL_BITMAPORDER_4321));
+    
+    mPackedOrder = rb_define_module_under(cPixelFormat, "PackedOrder");
+    /* define(`DEFINE_PACKEDORDER_CONST',`rb_define_const(mPackedOrder, "$1", UINT2NUM(SDL_PACKEDORDER_$1))') */
+    DEFINE_PACKEDORDER_CONST(NONE);
+    DEFINE_PACKEDORDER_CONST(XRGB);
+    DEFINE_PACKEDORDER_CONST(RGBX);
+    DEFINE_PACKEDORDER_CONST(ARGB);
+    DEFINE_PACKEDORDER_CONST(RGBA);
+    DEFINE_PACKEDORDER_CONST(XBGR);
+    DEFINE_PACKEDORDER_CONST(BGRX);
+    DEFINE_PACKEDORDER_CONST(ABGR);
+    DEFINE_PACKEDORDER_CONST(BGRA);
+
+    mArrayOrder = rb_define_module_under(cPixelFormat, "ArrayOrder");
+    /* define(`DEFINE_ARRAYORDER_CONST',`rb_define_const(mArrayOrder, "$1", UINT2NUM(SDL_ARRAYORDER_$1))') */
+    DEFINE_ARRAYORDER_CONST(NONE);
+    DEFINE_ARRAYORDER_CONST(RGB);
+    DEFINE_ARRAYORDER_CONST(RGBA);
+    DEFINE_ARRAYORDER_CONST(ARGB);
+    DEFINE_ARRAYORDER_CONST(BGR);
+    DEFINE_ARRAYORDER_CONST(BGRA);
+    DEFINE_ARRAYORDER_CONST(ABGR);
+
+    mPackedLayout = rb_define_module_under(cPixelFormat, "PackedLayout");
+    /* define(`DEFINE_PACKEDLAYOUT_CONST',`rb_define_const(mPackedLayout, "L_$1", UINT2NUM(SDL_PACKEDLAYOUT_$1))') */
+    rb_define_const(mPackedLayout, "NONE", UINT2NUM(SDL_PACKEDLAYOUT_NONE));
+    DEFINE_PACKEDLAYOUT_CONST(332);
+    DEFINE_PACKEDLAYOUT_CONST(4444);
+    DEFINE_PACKEDLAYOUT_CONST(1555);
+    DEFINE_PACKEDLAYOUT_CONST(5551);
+    DEFINE_PACKEDLAYOUT_CONST(565);
+    DEFINE_PACKEDLAYOUT_CONST(8888);
+    DEFINE_PACKEDLAYOUT_CONST(2101010);
+    DEFINE_PACKEDLAYOUT_CONST(1010102);
     
     {
         VALUE formats = rb_ary_new();
+        /* -: Array of all available formats */
         rb_define_const(cPixelFormat, "FORMATS", formats);
-#define DEFINE_PIXELFORMAT_CONST(t)                                     \
-        do {                                                            \
-            VALUE format = PixelFormat_new(SDL_PIXELFORMAT_##t);        \
-            rb_define_const(cPixelFormat, #t, format);                  \
-            rb_ary_push(formats, format);                               \
-        } while (0)
-        DEFINE_PIXELFORMAT_CONST(UNKNOWN);
+        /* define(`DEFINE_PIXELFORMAT_CONST',`do {
+            VALUE format = PixelFormat_new(SDL_PIXELFORMAT_$1);
+            $2
+            rb_define_const(cPixelFormat, "$1", format);
+            rb_ary_push(formats, format);
+        } while (0)')
+         */
+        
+        DEFINE_PIXELFORMAT_CONST(UNKNOWN, /* -: PixelFormat: Unused - reserved by SDL */);
         DEFINE_PIXELFORMAT_CONST(INDEX1LSB);
         DEFINE_PIXELFORMAT_CONST(INDEX1MSB);
         DEFINE_PIXELFORMAT_CONST(INDEX4LSB);
@@ -2832,6 +3160,16 @@ void rubysdl2_init_video(void)
 
 static VALUE mIMG;
 
+/*
+ * Document-module: SDL2::IMG
+ *
+ * This module provides the interface to SDL_image. You can load
+ * many kinds of image files using this modules.
+ * 
+ * This module provides only initialization interface {SDL2::IMG.init}.
+ * After calling init, you can load image files using {SDL2::Surface.load}.
+ */
+
 /*
  * @overload init(flags)
  *   Initialize SDL_image. 
@@ -2842,6 +3180,7 @@ static VALUE mIMG;
  *   * {SDL2::IMG::INIT_JPG}
  *   * {SDL2::IMG::INIT_PNG}
  *   * {SDL2::IMG::INIT_TIF}
+ *   * {SDL2::IMG::INIT_WEBP}
  *
  *   You need to initialize SDL_image to check whether specified format
  *   is supported by your environment. If your environment does not
@@ -2921,10 +3260,14 @@ void rubysdl2_init_image(void)
     rb_define_singleton_method(cSurface, "load", Surface_s_load, 1);
     rb_define_method(cRenderer, "load_texture", Renderer_load_texture, 1);
                      
-    
+
+    /* Initialize the JPEG loader */
     rb_define_const(mIMG, "INIT_JPG", INT2NUM(IMG_INIT_JPG));
+    /* Initialize the PNG loader */
     rb_define_const(mIMG, "INIT_PNG", INT2NUM(IMG_INIT_PNG));
+    /* Initialize the TIF loader */
     rb_define_const(mIMG, "INIT_TIF", INT2NUM(IMG_INIT_TIF));
+    /* Initialize the WEBP loader */
     rb_define_const(mIMG, "INIT_WEBP", INT2NUM(IMG_INIT_WEBP));
 }