Better docs on gradient coordinate behaviors

CHANGELOG.md

@@ -8,6 +8,7 @@
 
 Known issues
 * Masking SVGs onto an SVG backend will rasterize as an intermediate step. (#43)
+* Compatibility change: gradient coordinates for the `mask` option in `svg` and `png` commands are relative to the given x,y - NOT to card as it was before.
 
 ## v0.3.0
 * Masks! The `png` and `svg` commands can be used as if they are a mask, so you can color the icon with any color you like. Can be handy for switching to black-and-white, or for reusing the same image but different colors across cards.

lib/squib/api/image.rb

@@ -17,7 +17,7 @@ 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.
+    # @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. Note: the origin for gradient coordinates is at the given x,y, not at 0,0 as it is most other places.
     # @return [nil] Returns nil
     # @api public
     def png(opts = {})
@@ -52,7 +52,7 @@ 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.
+    # @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. Note: the origin for gradient coordinates is at the given x,y, not at 0,0 as it is most other places.
     # @return [nil] Returns nil
     # @api public
     def svg(opts = {})

samples/load_images.rb

@@ -13,8 +13,8 @@ Squib::Deck.new(width: 825, height: 1125, cards: 1) do
   #...but PNGs will warn if it's an upscale
 
   # We can also limit our rendering to a single object, if the SVG ID is set
-  # Squib prepends a #-sign if one is not specified
   svg file: 'spanner.svg', id: '#backdrop', x: 50, y: 350, width: 75, height: 75
+  # Squib prepends a #-sign if one is not specified
   svg file: 'spanner.svg', id: 'backdrop', x: 50, y: 450, width: 125, height: 125
 
   # WARNING! If you choose to use the SVG ID, the x-y coordinates are still
@@ -38,11 +38,11 @@ Squib::Deck.new(width: 825, height: 1125, cards: 1) do
   svg mask: '#00ff00',
       file: 'glass-heart.svg',
       x: 500, y: 600, width: 200, height: 200
-  svg mask: '(500,1000)(500,800) #333@0.0 #ccc@1.0 ',
+  svg mask: '(0,0)(0,500) #ccc@0.0 #333@1.0',
       file: 'glass-heart.svg',
       x: 500, y: 800, width: 200, height: 200
 
-  # Masks are based on transparency, so this is just a square
+  # Masks are based on the alpha channel, so this is just a magenta square
   png mask: :magenta, file: 'shiny-purse.png',
       x: 650, y: 950