Implementing mask feature for images

Fixes #32.

lib/squib/api/image.rb

@@ -17,16 +17,17 @@ module Squib
     # @option opts alpha [Decimal] (1.0) the alpha-transparency percentage used to blend this image. Supports Arrays, see {file:README.md#Arrays_and_Singleton_Expansion Arrays and Singleon Expansion}
     # @option opts blend [:none, :multiply, :screen, :overlay, :darken, :lighten, :color_dodge, :color_burn, :hard_light, :soft_light, :difference, :exclusion, :hsl_hue, :hsl_saturation, :hsl_color, :hsl_luminosity] (:none) the composite blend operator used when applying this image. See Blend Modes at http://cairographics.org/operators. Supports Arrays, see {file:README.md#Arrays_and_Singleton_Expansion Arrays and Singleon Expansion}
     # @option opts angle [FixNum] (0) Rotation of the in radians. Note that this rotates around the upper-left corner, making the placement of x-y coordinates slightly tricky. Supports Arrays, see {file:README.md#Arrays_and_Singleton_Expansion Arrays and Singleon Expansion}
+    # @option opts mask [String] (nil) If specified, the image will be used as a mask for the given color/gradient. Transparent pixels are ignored, opaque pixels are the given color.
     # @return [nil] Returns nil
     # @api public
     def png(opts = {})
-      opts = needs(opts, [:range, :files, :x, :y, :width, :height, :alpha, :layout, :blend, :angle])
+      opts = needs(opts, [:range, :files, :x, :y, :width, :height, :alpha, :layout, :blend, :angle, :mask])
       Dir.chdir(@img_dir) do
         @progress_bar.start('Loading PNG(s)', opts[:range].size) do |bar|
           opts[:range].each do |i|
             @cards[i].png(opts[:file][i],
                           opts[:x][i], opts[:y][i], opts[:width][i], opts[:height][i],
-                          opts[:alpha][i], opts[:blend][i], opts[:angle][i])
+                          opts[:alpha][i], opts[:blend][i], opts[:angle][i], opts[:mask][i])
             bar.increment
           end
         end
@@ -51,16 +52,17 @@ module Squib
     # @option opts alpha [Decimal] (1.0) the alpha-transparency percentage used to blend this image. Supports Arrays, see {file:README.md#Arrays_and_Singleton_Expansion Arrays and Singleon Expansion}
     # @option opts blend [:none, :multiply, :screen, :overlay, :darken, :lighten, :color_dodge, :color_burn, :hard_light, :soft_light, :difference, :exclusion, :hsl_hue, :hsl_saturation, :hsl_color, :hsl_luminosity] (:none) the composite blend operator used when applying this image. See Blend Modes at http://cairographics.org/operators. Supports Arrays, see {file:README.md#Arrays_and_Singleton_Expansion Arrays and Singleon Expansion}
     # @option opts angle [FixNum] (0) Rotation of the in radians. Note that this rotates around the upper-left corner, making the placement of x-y coordinates slightly tricky. Supports Arrays, see {file:README.md#Arrays_and_Singleton_Expansion Arrays and Singleon Expansion}
+    # @option opts mask [String] (nil) If specified, the image will be used as a mask for the given color/gradient. Transparent pixels are ignored, opaque pixels are the given color.
     # @return [nil] Returns nil
     # @api public
     def svg(opts = {})
-      p = needs(opts,[:range, :files, :svgid, :force_svgid, :x, :y, :width, :height, :layout, :alpha, :blend, :angle])
+      p = needs(opts,[:range, :files, :svgid, :force_svgid, :x, :y, :width, :height, :layout, :alpha, :blend, :angle, :mask])
       Dir.chdir(@img_dir) do
         @progress_bar.start('Loading SVG(s)', p[:range].size) do |bar|
           p[:range].each do |i|
             unless p[:force_id][i] && p[:id][i].to_s.empty?
               @cards[i].svg(p[:file][i], p[:id][i], p[:x][i], p[:y][i],
-                            p[:width][i], p[:height][i], p[:alpha][i], p[:blend][i], p[:angle][i])
+                            p[:width][i], p[:height][i], p[:alpha][i], p[:blend][i], p[:angle][i],p[:mask][i])
             end
             bar.increment
           end

lib/squib/constants.rb

@@ -25,6 +25,7 @@ module Squib
       :justify => false,
       :margin => 75,
       :markup => false,
+      :mask => nil,
       :offset => 1.1,
       :prefix => 'card_',
       :progress_bar => false,
@@ -95,6 +96,7 @@ module Squib
           :justify => :justify,
           :layout => :layout,
           :markup => :markup,
+          :mask => :mask,
           :rect_radius => :radius,
           :spacing => :spacing,
           :str => :str,

lib/squib/graphics/image.rb

@@ -14,8 +14,8 @@ module Squib
 
     # :nodoc:
     # @api private
-    def png(file, x, y, width, height, alpha, blend, angle)
-      Squib.logger.debug {"Rendering: #{file} @#{x},#{y} #{width}x#{height}, alpha: #{alpha}, blend: #{blend}, angle: #{angle}"}
+    def png(file, x, y, width, height, alpha, blend, angle, mask)
+      Squib.logger.debug {"Rendering: #{file} @#{x},#{y} #{width}x#{height}, alpha: #{alpha}, blend: #{blend}, angle: #{angle}, mask: #{mask}"}
       return if file.nil? or file.eql? ''
       png = Squib.cache_load_image(file)
       use_cairo do |cc|
@@ -30,14 +30,19 @@ module Squib
         cc.translate(-1 * x, -1 * y)
         cc.set_source(png, x, y)
         cc.operator = blend unless blend == :none
-        cc.paint(alpha)
+        if mask.nil?
+          cc.paint(alpha)
+        else
+          cc.set_source_squibcolor(mask)
+          cc.mask(png, x, y)
+        end
       end
     end
 
     # :nodoc:
     # @api private
-    def svg(file, id, x, y, width, height, alpha, blend, angle)
-      Squib.logger.debug {"Rendering: #{file}, id: #{id} @#{x},#{y} #{width}x#{height}, alpha: #{alpha}, blend: #{blend}, angle: #{angle}"}
+    def svg(file, id, x, y, width, height, alpha, blend, angle, mask)
+      Squib.logger.debug {"Rendering: #{file}, id: #{id} @#{x},#{y} #{width}x#{height}, alpha: #{alpha}, blend: #{blend}, angle: #{angle}, mask: #{mask}"}
       return if file.nil? or file.eql? ''
       svg = RSVG::Handle.new_from_file(file)
       width = svg.width if width == :native
@@ -50,9 +55,14 @@ module Squib
         cc.translate(x, y)
         cc.rotate(angle)
         cc.translate(-1 * x, -1 * y)
-        cc.set_source(tmp, x, y)
         cc.operator = blend unless blend == :none
-        cc.paint(alpha)
+        if mask.nil?
+          cc.set_source(tmp, x, y)
+          cc.paint(alpha)
+        else
+          cc.set_source_squibcolor(mask)
+          cc.mask(tmp, x, y)
+        end
       end
     end