devil 0.1.6 → 0.1.8

data/CHANGELOG

@@ -0,0 +1,50 @@
+2009-10-21
+version 0.1.8
+* made LANCZOS3 scaling filter the default for highquality thumbnails
+* changed clear color to DevIL default (mother of pearl and full alpha)
+* added blit function to HLA (high level API)
+* added mirror, edge_detect, emboss, enlarge_canvas, etc to HLA
+* added ILU_CENTER, ILU_LOWER_LEFT, ILU_PLACEMENT etc to LLA
+* include ILU and IL modules in Devil::Image now
+* made Devil::Image#show return self
+* made Devil::Image#show use a dup of the image (so a 'snapshot' is taken of image)
+* added Devil.set_options method to HLA
+* refactored HLA to use an 'action' method, saved code duplication of set_binding/error_check etc.
+
+2009-10-17 John Mair (Banisterfiend)
+* ruby_il.c added:
+* constants: IMAGE_DEPTH, ORIGIN_SET, CONV_PAL, CUR_IMAGE, ORIGIN_LOWER_LEFT, ORIGIN_LOWER_RIGHT
+* methods: Disable, OriginFunc, ClearColour, ClearImage.
+* Modified FromBlob method to restore old binding after use.
+* ruby_ilu.c added:
+* methods: EnlargeCanvas, EdgeDetectP, EdgeDetectS, Emboss, Mirror, SwapColours.
+* Modified Crop to now take z-axis parameters. (stick to original API as closely as possible)
+
+2009-10-15 John Mair (Banisterfiend)
+* hopefully fixed compile errors on SnowLeopard!
+* added error checking to Devil::load_image()
+* added monkeypatch to Gosu::Image::new() to transparently load multiple formats
+* updated some rdoc
+
+2009-10-13 John Mair (Banisterfiend)
+* version 0.1.6
+* added Gosu and TexPlay interoperability
+* ...bunch of other miscellaneous functionality
+* released gem
+
+2009-10-10 John Mair (Banisterfiend)
+* constants added to ruby_il.c:
+* IMAGE_WIDTH, IMAGE_HEIGHT, IMAGE_FORMAT, FILE_OVERWRITE
+* functions added to ruby_il.c:
+* ilEnable, ilGetInteger, ilConvertImage, ToBlob, ilCloneCurImage
+* conditional compilation added to ruby_il.c for LBM constant
+* functions added to ruby_ilu.c:
+* ilFlipImage, ilRotate, ilCrop
+* added Gosu and TexPlay interoperability
+* ...bunch of other miscellaneous functionality
+
+2009-10-06 John Mair (Banisterfiend)
+* ruby 1.9 compatibility
+
+2006-09-28 Jaroslaw Tworek <dev.jrx@gmail.com>
+* Initial release

data/README

@@ -1,27 +1,46 @@
-Devil version 0.1.6
-===================
+Ruby Devil version 0.1.8
+========================
 
 * Original author: Jaroslaw Tworek <dev.jrx@gmail.com>
-* Current maintainer: John Mair (banisterfiend) http://banisterfiend.wordpress.com
+* Current maintainer: John Mair (banisterfiend) [http://banisterfiend.wordpress.com]
 
 Ruby bindings for the Developer's Image Library
-You need DevIL installed to build this extension
+You need DevIL installed to use this extension
+
+The Ruby Devil Project page is here: [http://github.com/banister/devil]
+
 
 Installation Instructions:
 ==========================
 
 For debian:
+
 * install the libdevil and libdevil-dev packages
 
+For Gentoo:
+
+* emerge "media-libs/devil"
+
 For windows:
-* download devil.dll and ilu.dll from here http://openil.sourceforge.net
-* and copy devil.dll and ilu.dll to c:\windows\system\
+
+* download devil.dll and ilu.dll from [http://github.com/banister/devil/downloads]
+* and copy these files to c:\windows\system\
+
+For macosx:
+
+* sudo port install libdevil
 
 For other systems:
+
 * install libdevil and lib-devil-dev using your package manager
-* OR download and install the libraries from http://openil.sourceforge.net
+* OR download and install the libraries from [http://openil.sourceforge.net]
+
+After you've installed the DevIL libraries you install the gem by going:
+
+* gem install devil
 
 If you wish to use the Gosu and TexPlay extensions, it is necessary to also have:
+
 * the Gosu gem (gem install gosu)
 * the TexPlay gem (gem install texplay)
 * ruby-opengl (gem install ruby-opengl)

data/Rakefile

@@ -1,10 +1,14 @@
 require 'rake/clean'
-require 'rake/extensiontask'
+
+if RUBY_PLATFORM !~ /win32/
+    require 'rake/extensiontask'
+end
+
 require 'rake/gempackagetask'
 require 'rake/testtask'
 require 'rake/rdoctask'
 
-DEVIL_VERSION = "0.1.6"
+DEVIL_VERSION = "0.1.8"
 
 dlext = Config::CONFIG['DLEXT']
 
@@ -22,23 +26,23 @@ spec = Gem::Specification.new do |s|
     s.require_path = 'lib'
     s.homepage = "http://banisterfiend.wordpress.com"
 
-    if RUBY_PLATFORM =~ /win/
+    if RUBY_PLATFORM =~ /win32/
         s.platform = Gem::Platform::CURRENT
     else
         s.platform = Gem::Platform::RUBY
     end
 
-    if RUBY_PLATFORM !~ /win/
+    if RUBY_PLATFORM !~ /win32/
         s.extensions = FileList["ext/**/extconf.rb"]
     end
     
     s.has_rdoc = true
     s.extra_rdoc_files = ["README"]
     s.rdoc_options << '--main' << 'README'
-    s.files = ["Rakefile", "README", "LICENSE", "lib/devil.rb", "lib/devil/gosu.rb"] +
+    s.files = ["Rakefile", "README", "CHANGELOG", "LICENSE", "lib/devil.rb", "lib/devil/gosu.rb"] +
         FileList["ext/**/extconf.rb", "ext/**/*.h", "ext/**/*.c", "test/test*.rb", "test/*.png", "test/*.jpg"].to_a
 
-    if RUBY_PLATFORM =~ /win/
+    if RUBY_PLATFORM =~ /win32/
         s.files += ["lib/1.8/devil.so", "lib/1.9/devil.so"]
     end
 
@@ -51,10 +55,12 @@ end
 
 task :compile => :clean
 
-Rake::ExtensionTask.new('devil', spec)  do |ext|
-    ext.config_script = 'extconf.rb' 
-    ext.cross_compile = true                
-    ext.cross_platform = 'i386-mswin32'
+if RUBY_PLATFORM !~ /win32/
+    Rake::ExtensionTask.new('devil', spec)  do |ext|
+        ext.config_script = 'extconf.rb' 
+        ext.cross_compile = true                
+        ext.cross_platform = 'i386-mswin32'
+    end
 end
 
 Rake::TestTask.new do |t|

data/ext/devil/extconf.rb

@@ -3,10 +3,14 @@ require 'mkmf'
 if RUBY_PLATFORM =~ /mingw/
     $CFLAGS += ' -I/home/john/.rake-compiler/ruby/ruby-1.8.6-p287/include/'
     $LDFLAGS += ' -L/home/john/.rake-compiler/ruby/ruby-1.8.6-p287/lib/'
+elsif RUBY_PLATFORM =~ /darwin/
+
+    # this only works if you install devil via macports
+    $CFLAGS += ' -I/opt/local/include/'
+    $LDFLAGS += ' -L/opt/local/lib/'
 end
 
-puts "platform is #{RUBY_PLATFORM}"
-if RUBY_PLATFORM =~ /win/ || RUBY_PLATFORM =~ /mingw/
+if RUBY_PLATFORM =~ /(win32|mingw)/
     exit unless have_library("DevIL");
 else
     exit unless have_library("IL");

data/ext/devil/ruby_il.c

@@ -151,7 +151,7 @@ static VALUE il_GetData(VALUE obj) {
 /*     void* data = ImageData2Arr(rb_data); */
 
 /*     ILuint uint = ilCopyPixels(XOff, YOff, ZOff, Width, Height, Depth, Format, Type, data); */
-/*     return INT2FIX(uint);     */
+/*     return INT2FIX(uint); */
 /* } */
 
 static VALUE il_SetData(VALUE obj, VALUE rb_Data) {
@@ -242,6 +242,13 @@ static VALUE il_Enable(VALUE obj, VALUE rb_mode) {
     return flag ? Qtrue : Qfalse;
 }
 
+static VALUE il_Disable(VALUE obj, VALUE rb_mode) {
+    ILenum mode = NUM2INT(rb_mode);
+
+    ILboolean flag = ilDisable(mode);
+    return flag ? Qtrue : Qfalse;
+}
+
 static VALUE il_GetInteger(VALUE obj, VALUE rb_mode) {
     ILenum mode = NUM2INT(rb_mode);
 
@@ -258,13 +265,22 @@ static VALUE il_ConvertImage(VALUE obj, VALUE rb_destformat, VALUE rb_desttype)
     return flag ? Qtrue : Qfalse;
 }
 
+/* TODO: MAKE SURE NO MEMORY LEAKS! */
 /* this function is not actualy in the DevIL API, but im adding it here for convenience */
 static VALUE bf_ToBlob(VALUE obj)
 {
-    ILuint width, height;
+    ILuint width, height, saved_image, copy_image;
     char * img_ptr;
     VALUE blob;
+
+    saved_image = ilGetInteger(IL_CUR_IMAGE);
+
+    /* make a copy of the current image */
+    copy_image = ilCloneCurImage();
+
+    ilBindImage(copy_image);
     
+    /* ensure the image is int RGBA UNSIGNED_BYTE format for blob */
     ilConvertImage(IL_RGBA, IL_UNSIGNED_BYTE);
 
     width = ilGetInteger(IL_IMAGE_WIDTH);
@@ -274,6 +290,11 @@ static VALUE bf_ToBlob(VALUE obj)
 
     blob = rb_str_new(img_ptr, 4 * width * height);
 
+    /* restore saved binding */
+    ilBindImage(saved_image);
+
+    ilDeleteImages(1, &copy_image);
+
     return blob;
 }
 
@@ -282,17 +303,22 @@ static VALUE bf_FromBlob(VALUE obj, VALUE blob, VALUE rb_width, VALUE rb_height)
     ILubyte * data;
     ILuint width, height;
     ILuint image;
+    ILuint saved_image;
 
     width = NUM2INT(rb_width);
     height = NUM2INT(rb_height);
 
     data = (ILubyte *) RSTRING_PTR(blob);
 
+    saved_image = ilGetInteger(IL_CUR_IMAGE);
+
     ilGenImages(1, &image);
     ilBindImage(image);
 
     ilTexImage(width, height, 1, 4, IL_RGBA, IL_UNSIGNED_BYTE, data);
 
+    ilBindImage(saved_image);
+
     return INT2NUM(image);
 }
 
@@ -302,6 +328,32 @@ static VALUE il_CloneCurImage(VALUE obj)
 
     return INT2NUM(clone);
 }
+
+static VALUE il_OriginFunc(VALUE obj, VALUE rb_mode)
+{
+    ILenum mode = NUM2INT(rb_mode);
+
+    ILboolean flag = ilOriginFunc(mode);
+    return flag ? Qtrue : Qfalse;    
+}
+
+static VALUE il_ClearColour(VALUE obj, VALUE rb_red, VALUE rb_green, VALUE rb_blue, VALUE rb_alpha)
+{
+    ILubyte red = NUM2INT(rb_red);
+    ILubyte green = NUM2INT(rb_green);
+    ILubyte blue = NUM2INT(rb_blue);
+    ILubyte alpha = NUM2INT(rb_alpha);
+
+    ilClearColour(red, green, blue, alpha);
+
+    return Qnil;
+}
+
+static VALUE il_ClearImage(VALUE obj)
+{
+    ILboolean flag = ilClearImage();
+    return flag ? Qtrue : Qfalse;
+}
 /* end of banisterfiend additions */
 
 void
@@ -338,11 +390,15 @@ InitializeIL() {
 
     /* methods added by baniterfiend */
     rb_define_module_function(mIL, "Enable", il_Enable, 1);
+    rb_define_module_function(mIL, "Disable", il_Disable, 1);
     rb_define_module_function(mIL, "GetInteger", il_GetInteger, 1);
     rb_define_module_function(mIL, "ConvertImage", il_ConvertImage, 2);
     rb_define_module_function(mIL, "ToBlob", bf_ToBlob, 0);
     rb_define_module_function(mIL, "FromBlob", bf_FromBlob, 3);
     rb_define_module_function(mIL, "CloneCurImage", il_CloneCurImage, 0);
+    rb_define_module_function(mIL, "OriginFunc", il_OriginFunc, 1);
+    rb_define_module_function(mIL, "ClearColour", il_ClearColour, 4);
+    rb_define_module_function(mIL, "ClearImage", il_ClearImage, 0);
     /* end of methods added by banisterfiend */
     
     //////////////////////////////////
@@ -434,11 +490,17 @@ InitializeIL() {
     rb_define_const(mIL, "LIB_MNG_ERROR", INT2NUM(IL_LIB_MNG_ERROR));
     rb_define_const(mIL, "UNKNOWN_ERROR", INT2NUM(IL_UNKNOWN_ERROR));
 
-    // CONSTANTS BELOW ADDED BY BANISTERFIEND
+    /* CONSTANTS BELOW ADDED BY BANISTERFIEND */
+    rb_define_const(mIL, "IMAGE_DEPTH", INT2NUM(IL_IMAGE_DEPTH));
     rb_define_const(mIL, "IMAGE_WIDTH", INT2NUM(IL_IMAGE_WIDTH));
     rb_define_const(mIL, "IMAGE_HEIGHT", INT2NUM(IL_IMAGE_HEIGHT));
     rb_define_const(mIL, "IMAGE_FORMAT", INT2NUM(IL_IMAGE_FORMAT));
     rb_define_const(mIL, "FILE_OVERWRITE", INT2NUM(IL_FILE_OVERWRITE));
+    rb_define_const(mIL, "ORIGIN_SET", INT2NUM(IL_ORIGIN_SET));
+    rb_define_const(mIL, "CONV_PAL", INT2NUM(IL_CONV_PAL));
+    rb_define_const(mIL, "CUR_IMAGE", INT2NUM(IL_CUR_IMAGE));
+    rb_define_const(mIL, "ORIGIN_LOWER_LEFT", INT2NUM(IL_ORIGIN_LOWER_LEFT));
+    rb_define_const(mIL, "ORIGIN_UPPER_LEFT", INT2NUM(IL_ORIGIN_UPPER_LEFT));
 }
 //////////////////////////////////////////
 

data/ext/devil/ruby_ilu.c

@@ -103,17 +103,66 @@ static VALUE ilu_Rotate(VALUE obj, VALUE rb_angle) {
     return flag ? Qtrue : Qfalse;
 }
 
-static VALUE ilu_Crop(VALUE obj, VALUE rb_XOff, VALUE rb_YOff, VALUE rb_width, VALUE rb_height)
+static VALUE ilu_Crop(VALUE obj, VALUE rb_XOff, VALUE rb_YOff, VALUE rb_ZOff, VALUE rb_width, VALUE rb_height, VALUE rb_depth)
 {
     ILuint XOff = NUM2INT(rb_XOff);
     ILuint YOff = NUM2INT(rb_YOff);
+    ILuint ZOff = NUM2INT(rb_ZOff);
     ILuint width = NUM2INT(rb_width);
     ILuint height = NUM2INT(rb_height);
+    ILuint depth = NUM2INT(rb_depth);
                        	
-    ILboolean flag = iluCrop(XOff, YOff, 1, width, height, 1);
+    ILboolean flag = iluCrop(XOff, YOff, ZOff, width, height, depth);
 
     return flag ? Qtrue : Qfalse;
 }
+
+static VALUE ilu_EnlargeCanvas(VALUE obj, VALUE rb_width, VALUE rb_height, VALUE rb_depth)
+{
+    ILuint width = NUM2INT(rb_width);
+    ILuint height = NUM2INT(rb_height);
+    ILuint depth = NUM2INT(rb_depth);
+
+    ILboolean flag = iluEnlargeCanvas(width, height, depth);
+
+    return flag ? Qtrue : Qfalse;
+}
+
+static VALUE ilu_EdgeDetectP(VALUE obj)
+{
+    ILboolean flag = iluEdgeDetectP();
+
+    return flag ? Qtrue : Qfalse;    
+}
+
+static VALUE ilu_EdgeDetectS(VALUE obj)
+{
+    ILboolean flag = iluEdgeDetectS();
+
+    return flag ? Qtrue : Qfalse;    
+}
+
+static VALUE ilu_Emboss(VALUE obj)
+{
+    ILboolean flag = iluEmboss();
+
+    return flag ? Qtrue : Qfalse;    
+}
+
+static VALUE ilu_Mirror(VALUE obj)
+{
+    ILboolean flag = iluMirror();
+
+    return flag ? Qtrue : Qfalse;    
+}
+
+static VALUE ilu_SwapColours(VALUE obj)
+{
+    ILboolean flag = iluSwapColours();
+
+    return flag ? Qtrue : Qfalse;    
+}
+
 /* end of functions added by banisterfiend */
 
 void
@@ -138,9 +187,16 @@ InitializeILU() {
     /* methods added by banisterfiend */
     rb_define_module_function(mILU, "FlipImage",  ilu_FlipImage, 0);
     rb_define_module_function(mILU, "Rotate",  ilu_Rotate, 1);
-    rb_define_module_function(mILU, "Crop",  ilu_Crop, 4);
+    rb_define_module_function(mILU, "Crop",  ilu_Crop, 6);
+    rb_define_module_function(mILU, "EnlargeCanvas",  ilu_EnlargeCanvas, 3);
+    rb_define_module_function(mILU, "EdgeDetectP", ilu_EdgeDetectP, 0);
+    rb_define_module_function(mILU, "EdgeDetectS", ilu_EdgeDetectS, 0);
+    rb_define_module_function(mILU, "Emboss", ilu_Emboss, 0);
+    rb_define_module_function(mILU, "Mirror", ilu_Mirror, 0);
+    rb_define_module_function(mILU, "SwapColours", ilu_SwapColours, 0);
     /* end of functions added by banisterfiend */
 
+    /* constants added by banisterfiend */
     rb_define_const(mILU, "FILTER", INT2NUM(ILU_FILTER));
     rb_define_const(mILU, "NEAREST", INT2NUM(ILU_NEAREST));
     rb_define_const(mILU, "LINEAR", INT2NUM(ILU_LINEAR));
@@ -151,4 +207,13 @@ InitializeILU() {
     rb_define_const(mILU, "SCALE_BSPLINE", INT2NUM(ILU_SCALE_BSPLINE));
     rb_define_const(mILU, "SCALE_LANCZOS3", INT2NUM(ILU_SCALE_LANCZOS3));
     rb_define_const(mILU, "SCALE_MITCHELL", INT2NUM(ILU_SCALE_MITCHELL));
+
+    rb_define_const(mILU, "PLACEMENT", INT2NUM(ILU_PLACEMENT));
+    rb_define_const(mILU, "UPPER_LEFT", INT2NUM(ILU_UPPER_LEFT));
+    rb_define_const(mILU, "LOWER_LEFT", INT2NUM(ILU_LOWER_LEFT));
+    rb_define_const(mILU, "LOWER_RIGHT", INT2NUM(ILU_LOWER_RIGHT));
+    rb_define_const(mILU, "UPPER_RIGHT", INT2NUM(ILU_UPPER_RIGHT));
+    rb_define_const(mILU, "CENTER", INT2NUM(ILU_CENTER));
+    /* end of constants added by banisterfiend */
+
 }

data/lib/devil.rb

@@ -1,3 +1,5 @@
+# (C) John Mair 2009, under the MIT licence
+
 require 'rbconfig'
 
 direc = File.dirname(__FILE__)
@@ -14,7 +16,10 @@ end
 
 # Provides a high level wrapper for the low-level DevIL Ruby bindings
 module Devil
-    VERSION = '0.1.6'
+    include IL
+    include ILU
+
+    VERSION = '0.1.8'
     
     class << self
 
@@ -25,6 +30,11 @@ module Devil
             IL.BindImage(name)
             IL.LoadImage(file)
 
+            if (error_code = IL.GetError) != IL::NO_ERROR
+                raise RuntimeError, "an error occured while trying to "+
+                    "load the image #{file}. #{ILU.ErrorString(error_code)}"
+            end
+
             img = Image.new(name, file)
             if block
                 block.call(img)
@@ -33,27 +43,88 @@ module Devil
             img
         end
 
+        alias_method :with_image, :load_image
+        alias_method :load, :load_image
+        
         # convert an image +blob+ with +width+ and +height+
         # to a bona fide image
         def from_blob(blob, width, height)
             Image.new(IL.FromBlob(blob, width, height), nil)
         end
 
-        # initializes Devil and sets defaults
+        # configure Devil.
+        # accepts hash parameters: :scale_filter, :placement, :clear_color,
+        # :window_size, :edge_filter.
+        #
+        # :scale_filter accepts a valid scaling algorithm: (default is LANCZOS3).
+        # Devil::NEAREST, Devil::LINEAR, Devil::BILINEAR, Devil::SCALE_BOX,
+        # Devil::SCALE_TRIANGLE, Devil::SCALE_BELL, Devil::SCALE_BSPLINE,
+        # Devil::SCALE_LANCZOS3, Devil::SCALE_MITCHELL
+        #
+        # :placement determines where in the canvas the image will be placed after
+        # the canvas has been enlarged using the 'enlarge_canvas' method.
+        # Valid parameters are: Devil::Center, Devil::LOWER_LEFT, Devil::UPPER_RIGHT, etc
+        #
+        # :clear_color  sets the current clearing colour to be used by future
+        # calls to clear. rotate and enlarge_canvas both use these values to
+        # clear blank space in images, too.
+        # e.g Devil.set_options(:clear_color => [255, 255, 0, 255])
+        # Above sets the clear color to yellow with full opacity.
+        #
+        # :window_size sets the display window size Gosu will use when displaying images
+        # that invoked the 'show' method. (default is 1024 x 768)
+        # e.g Devil.set_options(:window_size => [2000, 768])
+        # Example above sets a window size of 2000x768.
+        # Note: :window_size is only relevant when require 'devil/gosu' is used.
+        #
+        # :edge_filter sets the edge detection algorithm to use when invoking
+        # the 'edge_detect' method. (defaults to :prewitt)
+        # Allowed values are :prewitt and :sobel
+        def set_options(options={})
+            @options.merge!(options)
+
+            # update the scale_filter 
+            ILU.ImageParameter(ILU::FILTER, @options[:scale_filter])
+            ILU.ImageParameter(ILU::PLACEMENT, @options[:placement])
+            IL.ClearColour(*@options[:clear_color])
+        end
+
+        # return the current Devil configuration.
+        def get_options
+            @options
+        end
+
+        # initializes Devil and sets defaults.
         # This method should never need to be called directly.
         def init
             # initialize DevIL
             IL.Init
+            ILU.Init
 
-            # default options
-            IL.Enable(IL::FILE_OVERWRITE)
-            ILU.ImageParameter(ILU::FILTER, ILU::BILINEAR) 
+            set_option_defaults
         end
 
-        alias_method :with_image, :load_image
-        alias_method :load, :load_image
-    end
+        private
+        
+        def set_option_defaults
+            @options = {
+                :scale_filter => ILU::SCALE_LANCZOS3,
+                :edge_filter => :prewitt,
+                :window_size => [1024, 768],
+                :clear_color => [255, 248, 230, 0],
+                :placement => ILU::CENTER,
+            }
+            
+            # configurable options
+            ILU.ImageParameter(ILU::FILTER, @options[:scale_filter])
+            ILU.ImageParameter(ILU::PLACEMENT, @options[:placement])
+            IL.ClearColour(*@options[:clear_color])
 
+            # fixed options
+            IL.Enable(IL::FILE_OVERWRITE)
+        end
+    end
+ 
     class Image
         attr_reader :name, :file
 
@@ -64,83 +135,147 @@ module Devil
             ObjectSpace.define_finalizer( self, proc { IL.DeleteImages(1, [name]) } )
         end
         
-        # returns the width of the image
+        # returns the width of the image.
         def width
-            set_binding
-            IL.GetInteger(IL::IMAGE_WIDTH)
+            action { IL.GetInteger(IL::IMAGE_WIDTH) }
         end
 
-        # returns the height of the image
+        alias_method :columns, :width
+
+        # returns the height of the image.
         def height
-            set_binding
-            IL.GetInteger(IL::IMAGE_HEIGHT)
+            action { IL.GetInteger(IL::IMAGE_HEIGHT) }
         end
 
+        alias_method :rows, :height
+
         # saves the image to +file+. If no +file+ is provided default to the opened file.
         def save(file = @file)
-            set_binding
-            IL.SaveImage(file)
+            raise "This image does not have an associated file. Please provide an explicit file name when saving." if !file
+            
+            action { IL.SaveImage(file) }
             self
         end
         
         # resize the image to +width+ and +height+. Aspect ratios of the image do not have to be the same.
         def resize(width, height)
-            set_binding
-            ILU.Scale(width, height, 1)
+            action { ILU.Scale(width, height, 1) }
             self
         end
 
-        # Creates a proportional thumbnail of the image scaled so its longest
-        # edge is resized to +size+ 
+        # Creates a proportional thumbnail of the image scaled so its longest.
+        # edge is resized to +size+.
         def thumbnail(size)
+
             # this thumbnail code from image_science.rb
-            
             w, h = width, height
             scale = size.to_f / (w > h ? w : h)
             resize((w * scale).to_i, (h * scale).to_i)
             self
         end
 
-        # return a deep copy of the current image
+        # return a deep copy of the current image.
         def dup
-            set_binding
-            Image.new(IL.CloneCurImage, nil)
+            new_image_name = action { IL.CloneCurImage }
+            Image.new(new_image_name, nil)
         end
 
-        # crop the current image
-        # +xoff+ number of pixels to skip in x direction
-        # +yoff+ number of pixels to skip in y direction
-        # +width+ number of pixels to preserve in x direction
-        # +height+ number of pixels to preserve in y direction
+        alias_method :clone, :dup
+
+        # crop the current image.
+        # +xoff+ number of pixels to skip in x direction.
+        # +yoff+ number of pixels to skip in y direction.
+        # +width+ number of pixels to preserve in x direction.
+        # +height+ number of pixels to preserve in y direction.
         def crop(xoff, yoff, width, height)
-            set_binding
-            ILU.Crop(xoff, yoff, width, height)
+            action { ILU.Crop(xoff, yoff, 1, width, height, 1) }
+            self
+        end
+
+        # enlarge the canvas of current image to +width+ and +height+.
+        def enlarge_canvas(width, height)
+            if width < self.width || height < self.height
+                raise "width and height parameters must be larger than current image width and height"
+            end
+            
+            action { ILU.EnlargeCanvas(width, height, 1) }
+            self
+        end
+
+        # splice the +source+ image into current image at position +x+ and +y+.
+        # Takes an optional +:crop+ hash parameter that has the following format: +:crop => [sx, sy, width, height]+
+        # +sx+, +sy+, +width, +height+ crop the source image to be spliced.
+        # +sx+ is how many pixels to skip in x direction of source image.
+        # +sy+ is how many pixels to skip in y direction of source image.
+        # +width+ number of pixels to preserve in x direction of source image.
+        # +height+ number of pixels to preserve in y direction of source image.
+        # if no +:crop+ parameter is provided then the whole image is spliced in.
+        def blit(source, x, y, options = {})
+            options = {
+                :crop => [0, 0, source.width, source.height]
+            }.merge!(options)
+            
+            action do
+                IL.Blit(source.name, x, y, 0, options[:crop][0], options[:crop][1], 0,
+                        options[:crop][2], options[:crop][3], 1)
+            end
+            
+            self
+        end
+
+        alias_method :composite, :blit
+
+        # reflect image about its y axis.
+        def mirror
+            action { ILU.Mirror }
+            self
+        end
+
+        # use prewitt or sobel filters to detect the edges in the current image.
+        def edge_detect
+            case Devil.get_options[:edge_filter]
+            when :prewitt
+                action { ILU.EdgeDetectP }
+            when :sobel
+                action { ILU.EdgeDetectS }
+            else
+                raise "No such edge filter #{Devil.get_options[:edge_filter]}. Use :prewitt or :sobel"
+            end
+            self
+        end
+
+        # embosses an image, causing it to have a "relief" feel to it using a convolution filter.
+        def emboss
+            action { ILU.Emboss }
+            self
+        end
+
+        # applies a strange color distortion effect to the image giving  a preternatural feel
+        def alienify
+            action { ILU.Alienify }
             self
         end
 
         # performs a gaussian blur on the image. The blur is performed +iter+ times.
         def blur(iter)
-            set_binding
-            ILU.BlurGaussian(iter)
+            action { ILU.BlurGaussian(iter) }
             self
         end
 
-        # 'pixelize' the image using a pixel size of +pixel_size+
+        # 'pixelize' the image using a pixel size of +pixel_size+.
         def pixelize(pixel_size)
-            set_binding
-            ILU.Pixelize(pixel_size)
+            action { ILU.Pixelize(pixel_size) }
             self
         end
 
         # add random noise to the image. +factor+ is the tolerance to use.
-        # accepeted values range from 0.0 - 1.0
+        # accepeted values range from 0.0 - 1.0.
         def noisify(factor)
-            set_binding
-            ILU.Noisify(factor)
+            action { ILU.Noisify(factor) }
             self
         end
 
-        # The sharpening +factor+ must be in the range of 0.0 - 2.5. A value of 1.0 for the sharpening
+        # The sharpening +factor+ must be in the range of 0.0 - 2.5. A value of 1.0 for the sharpening.
         # factor will have no effect on the image. Values in the range 1.0 - 2.5 will sharpen the
         # image, with 2.5 having the most pronounced sharpening effect. Values from 0.0 to 1.0 do
         # a type of reverse sharpening, blurring the image. Values outside of the 0.0 - 2.5 range
@@ -149,8 +284,7 @@ module Devil
         # The number of +iter+ (iterations) to perform will usually be 1, but to achieve more sharpening,
         # increase the number of iterations. 
         def sharpen(factor, iter)
-            set_binding
-            ILU.Sharpen(factor, iter)
+            action { ILU.Sharpen(factor, iter) }
             self
         end
 
@@ -160,66 +294,77 @@ module Devil
         # Values in the range 0.0 - 1.0 darken the image
         # Values above 1.0 brighten the image.
         def gamma_correct(factor)
-            set_binding
-            ILU.GammaCorrect(factor)
+            action { ILU.GammaCorrect(factor) }
             self
         end
 
         # invert the color of every pixel in the image.
-        def negative
-            set_binding
-            ILU.Negative
+        def negate
+            action { ILU.Negative }
             self
         end
 
+        alias_method :negative, :negate
+
         # +factor+ describes desired contrast to use
         # A value of 1.0 has no effect on the image.
         # Values between 1.0 and 1.7 increase the amount of contrast (values above 1.7 have no effect)
-        # Valid range of +factor+ is 0.0 - 1.7
+        # Valid range of +factor+ is 0.0 - 1.7.
         def contrast(factor)
-            set_binding
-            ILU.Contrast(factor)
+            action { ILU.Contrast(factor) }
             self
         end
 
         # darkens the bright colours and lightens the dark
         # colours, reducing the contrast in an image or 'equalizing' it.
         def equalize
-            set_binding
-            ILU.Equalize
+            action { ILU.Equalize }
             self
         end
 
-        # returns the image data in the form of a ruby string
-        # The image data is formatted to RGBA / UNSIGNED BYTE
+        # returns the image data in the form of a ruby string.
+        # The image data is formatted to RGBA / UNSIGNED BYTE.
         def to_blob
-            set_binding
-            IL.ToBlob
+            action { IL.ToBlob }
         end
 
-        # flip the image about its x axis
+        # flip the image about its x axis.
         def flip
-            set_binding
-            ILU.FlipImage
+            action { ILU.FlipImage }
             self
         end
 
-        # rotate an image about its central point by +angle+ degrees
+        # rotate an image about its central point by +angle+ degrees (counter clockwise).
         def rotate(angle)
-            set_binding
-            ILU.Rotate(angle)
+            action { ILU.Rotate(angle) }
             self
         end
 
-        alias_method :columns, :width
-        alias_method :rows, :height
+        #  simply clears the image to the 'clear color' (specified using Devil.set_options(:clear_color => [r, g, b, a])
+        def clear
+            action { IL.ClearImage }
+            self
+        end
 
         private
-        
+
         def set_binding
             IL.BindImage(@name)
         end
 
+        def error_check
+            if (error_code = IL.GetError) != IL::NO_ERROR
+                raise RuntimeError, "An error occured. #{ILU.ErrorString(error_code)}"
+            end
+        end
+
+        def action
+            set_binding
+            result = yield
+            error_check
+            
+            result
+        end
     end
 end
 

data/lib/devil/gosu.rb

@@ -1,19 +1,19 @@
 require 'texplay'
 require 'devil'
 
+# monkey patches for TexPlay module (and by proxy the Gosu::Image class)
 module TexPlay
 
     # save a Gosu::Image to +file+
     # This method is only available if require 'devil/gosu' is used
     def save(file)
         capture { 
-            save_image = Devil.from_blob(self.to_blob, self.width, self.height)
-            save_image.flip
-            save_image.save(file)
+            to_devil.save(file)
         }
+        self
     end
 
-    # convert a Gosu::Image to a Devil::Image
+    # convert a Gosu::Image to a Devil::Image.
     # This method is only available if require 'devil/gosu' is used
     def to_devil
         devil_img = nil
@@ -25,9 +25,10 @@ module TexPlay
     end
 end
 
+# monkey patches for Gosu::Window class
 class Gosu::Window
 
-    # return a screenshot of the framebuffer as a Devil::Image
+    # return a screenshot of the framebuffer as a Devil::Image.
     # This method is only available if require 'devil/gosu' is used
     def screenshot
         require 'opengl'
@@ -54,10 +55,27 @@ class Gosu::Window
     end
 end
 
+class Gosu::Image
+    class << self
+        alias_method :original_new_redux, :new
+        
+        # monkey patching to support multiple image formats.
+        # This method is only available if require 'devil/gosu' is used
+        def new(window, file, *args, &block)
+            if file.respond_to?(:to_blob) || file =~ /\.(bmp|png)$/
+                original_new_redux(window, file, *args, &block)
+            else 
+                original_new_redux(window, Devil.load(file), *args, &block)
+            end
+        end
+    end
+end
+
 class Devil::Image
 
     # convert a Devil::Image to a Gosu::Image.
     # Must provide a +window+ parameter, as per Gosu::Image#new()
+    # This method is only available if require 'devil/gosu' is used
     def to_gosu(window)
         Gosu::Image.new(window, self)
     end
@@ -66,13 +84,15 @@ class Devil::Image
     # if +x+ and +y+ are specified then show the image centered at this location, otherwise
     # draw the image at the center of the screen 
     # This method is only available if require 'devil/gosu' is used
-    def show(x = 512, y = 384)
+    def show(x = Devil.get_options[:window_size][0] / 2,
+             y = Devil.get_options[:window_size][1] / 2)
+        
         if !Devil.const_defined?(:Window)
             c = Class.new(Gosu::Window) do
                 attr_accessor :show_list
                 
                 def initialize
-                    super(1024, 768, false)
+                    super(Devil.get_options[:window_size][0], Devil.get_options[:window_size][1], false)
                     @show_list = []
                 end
 
@@ -89,8 +109,10 @@ class Devil::Image
 
             at_exit { @@window.show }
         end
-        
-        @@window.show_list.push :image => Gosu::Image.new(@@window, self), :x => x, :y => y
-    end
 
+        # note we dup the image so the displayed image is a snapshot taken at the time #show is invoked
+        @@window.show_list.push :image => Gosu::Image.new(@@window, self.dup), :x => x, :y => y
+
+        self
+    end
 end

data/test/test_blit.rb

@@ -0,0 +1,22 @@
+$direc = File.dirname(__FILE__)
+
+$LOAD_PATH.push("#{$direc}/../lib/")
+
+require 'rubygems'
+require 'devil/gosu'
+
+Devil.with_image("#{$direc}/texture.png") do |img|
+    img2 = Devil.load("#{$direc}/red.png")
+
+    img.show(200,200)
+
+    img.blit img2, 100, 100, :crop => [0, 0, img2.width / 2, img2.height / 2]
+
+    img.show
+end
+
+
+
+                   
+
+

data/test/test_clone_and_crop.rb

@@ -5,7 +5,7 @@ $LOAD_PATH.push("#{direc}/../lib/")
 require 'rubygems'
 require "devil/gosu"
 
-img = Devil.load_image("#{direc}/texture.png") 
+img = Devil.load_image("#{direc}/texture.jpg") 
 
 img.crop(100,100, 200, 200)
 img_dup = img.dup

data/test/test_gosu_load.rb

@@ -3,16 +3,13 @@ $direc = File.dirname(__FILE__)
 $LOAD_PATH.push("#{$direc}/../lib/")
 
 require 'rubygems'
-require 'gosu'
-require 'devil'
+require 'devil/gosu'
 
 class W < Gosu::Window
     def initialize
         super(1024, 768, false, 20)
 
-        img = Devil.load_image("#{$direc}/texture.jpg")
-
-        @img = Gosu::Image.new(self, img)
+        @img = Gosu::Image.new(self, "#{$direc}/texture.jpg")
     end
     
     def draw

data/test/test_new_api.rb

@@ -1,23 +1,23 @@
-direc = File.dirname(__FILE__)
+$direc = File.dirname(__FILE__)
 
-$LOAD_PATH.push("#{direc}/../lib/")
+$LOAD_PATH.push("#{$direc}/../lib/")
 
 require 'rubygems'
 require "devil"
 
-Devil.load_image("#{direc}/texture.png") do |img|
+Devil.with_image("#{$direc}/texture.png") do |img|
     img.negative
-    img.save("#{direc}/texture_neg.png")
+    img.save("#{$direc}/texture_neg.png")
 end
 
-img = Devil.load_image("#{direc}/texture.png")
-bink = Devil.load_image("#{direc}/texture.png")
+img = Devil.load_image("#{$direc}/texture.png")
+bink = Devil.load_image("#{$direc}/texture.png")
 
 img.gamma_correct(1.6)
 bink.resize(50, 50)
 
-img.save("#{direc}/texture_blur.png")
-bink.save("#{direc}/texture_tiny.png")
+img.save("#{$direc}/texture_gamma.png")
+bink.save("#{$direc}/texture_tiny.png")
 
 
                    

data/test/test_scale_algos.rb

@@ -0,0 +1,30 @@
+require 'rubygems'
+require 'devil'
+ 
+algorithms = {
+    ILU::NEAREST => :nearest,
+    ILU::LINEAR => :linear,
+    ILU::BILINEAR => :bilinear,
+    ILU::SCALE_BOX => :scale_box,
+    ILU::SCALE_TRIANGLE => :scale_triangle,
+    ILU::SCALE_BELL => :scale_bell,
+    ILU::SCALE_BSPLINE => :scale_bspline,
+    ILU::SCALE_LANCZOS3 => :scale_lanczos3,
+    ILU::SCALE_MITCHELL => :scale_mitchell
+}
+ 
+ 
+algorithms.each do |key, value|
+  puts "Generating image using filter: #{value}"
+  IL.Init
+ 
+  name = IL.GenImages(1)[0]
+  IL.BindImage(name)
+  IL.LoadImage("texture.jpg")
+  ILU.ImageParameter(ILU::FILTER, key)
+ 
+  ILU.Scale(100, 100, 1)
+  IL.Enable(IL::FILE_OVERWRITE)
+  IL.SaveImage("scaling_test_#{value}.jpg")
+  
+end

data/test/test_thumbnail.rb

@@ -6,7 +6,6 @@ require 'rubygems'
 require 'devil/gosu'
 
 Devil.load("texture.png") do |img|
-    img.thumbnail(300)
-    img.show
+    img.thumbnail(150).show
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: devil
 version: !ruby/object:Gem::Version 
-  version: 0.1.6
+  version: 0.1.8
 platform: ruby
 authors: 
 - Jaroslaw Tworek, John Mair (banisterfiend)
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-10-12 00:00:00 -04:00
+date: 2009-10-20 00:00:00 -04:00
 default_executable: 
 dependencies: []
 
@@ -24,6 +24,7 @@ extra_rdoc_files:
 files: 
 - Rakefile
 - README
+- CHANGELOG
 - LICENSE
 - lib/devil.rb
 - lib/devil/gosu.rb
@@ -32,7 +33,9 @@ files:
 - ext/devil/ruby_devil_ext.c
 - ext/devil/ruby_il.c
 - ext/devil/ruby_ilu.c
+- test/test_blit.rb
 - test/test_gosu_load.rb
+- test/test_scale_algos.rb
 - test/test_new_api.rb
 - test/test_clone_and_crop.rb
 - test/test_gosu_show.rb
@@ -41,6 +44,7 @@ files:
 - test/test_thumbnail.rb
 - test/tank.png
 - test/texture.png
+- test/red.png
 - test/texture.jpg
 has_rdoc: true
 homepage: http://banisterfiend.wordpress.com