diff --git a/README b/README
index cf83e60..cd35ab8 100644
--- a/README
+++ b/README
@@ -19,7 +19,128 @@ sudo gem install imageruby
 Full API documentation can be found on:
 http://tario.github.com/imageruby/doc/
 
-== Usage
+== Examples
+
+NOTE: Examples loads and saves bitmap files, imageruby-bmp gem must be installed in order
+to get the examples work
+
+=== Create and save a black image
+
+  require "rubygems"
+  require "imageruby"
+
+  include ImageRuby
+
+  #  creates an image of 150x150 pixels filled with black
+  image = ImageRuby::Image.new(150,150, Color.black)
+
+  begin
+  # this only work if imageruby-bmp gem is installed
+  image.save("black.bmp", :bmp)
+  rescue
+    print "Error while trying to save, you must install imageruby-bmp gem"
+  end
+
+=== Create an image with vertical stripes filled with default named colors
+
+  require "rubygems"
+  require "imageruby"
+
+  include ImageRuby
+
+  print "list of named colors:\n"
+  print "--------------------------\n"
+
+  colors = Array.new
+
+  Color.named_colors.each do |name, color|
+	print "#{name}: #{color.inspect}\n"
+	colors << color
+  end
+
+  image = Image.new( colors.count * 32, 512)
+
+  x = 0
+  colors.each do |color|
+  image[x..x+31, 0..511] = Image.new(32,512,color)
+  x = x + 32
+  end
+
+  image.save("colors.bmp", :bmp)
+
+=== Gradient using block parameter
+
+  require "rubygems"
+  require "imageruby"
+
+  include ImageRuby
+
+  gradient_images = Array.new
+
+  gradient_images << Image.new(64,64) {|x,y| 
+    Color.from_rgb(x*4,y*4,0) 
+  }
+
+  gradient_images << Image.new(64,64) {|x,y| 
+    Color.from_rgb(0,x*4,y*4) 
+  }
+
+  gradient_images << Image.new(64,64) {|x,y| 
+    Color.from_rgb(y*4,0,x*4) 
+  }
+
+  (0..gradient_images.count-1).each do |i|
+	gradient_images[i].save("gradient#{i}.bmp", :bmp)
+  end
+
+  all_gradient = Image.new(96*gradient_images.count, 96)
+
+  (0..gradient_images.count-1).each do |i|
+	all_gradient.draw!(i*96+16, 16, gradient_images[i])
+  end
+
+  all_gradient.save("gradients.bmp", :bmp)
+
+
+=== Draw with mask
+
+  require "rubygems"
+  require "imageruby"
+
+  include ImageRuby
+
+  colors = Image.from_file("colors.bmp")
+  gradients = Image.from_file("gradients.bmp")
+
+  without_mask = colors.draw(128,192,gradients)
+  without_mask.save("without_mask.bmp", :bmp)
+
+  with_mask = colors.draw(128,192,gradients.mask(Color.black))
+  with_mask.save("with_mask.bmp", :bmp)
+
+=== Draw with transparency effects
+
+  require "rubygems"
+  require "imageruby"
+
+  include ImageRuby
+
+  colors = Image.from_file("colors.bmp")
+  gradients = Image.from_file("gradients.bmp")
+
+  transparent_black = Color.black
+  transparent_black.a = 128
+
+
+  colors.draw(128,192,gradients.color_replace(Color.black, transparent_black)).save("sample1.bmp", :bmp)
+
+  half_transparent = gradients.map_pixel{ |x,y,c|
+	c.a = 128 if x >144
+	c
+  }
+  colors.draw(128,192,half_transparent).save("sample2.bmp", :bmp)
+
+
 
 == Copying