Add support for custom draw offsets

Acetate debug drawing needs to align properly with sprites. To do so,
Acetate adjusts the draw offset for the drawing context before calling
debugDraw on each sprite, but it lacks information about any adjustments
to this offset made by the application. This change both provides
better out-of-the-box behavior for apps which use custom draw offsets,
and a means to manually cache the offset for a given sprite as needed
to enable proper debug drawing.

README.md

@@ -97,6 +97,10 @@ You can also easily display additional information and visualizations unique to
 on to learn how to implement custom debug drawing for your sprite classes and customize the debug
 string displayed as you cycle through them in debug mode.
 
+_**NOTE:** If your game adjusts the draw offset, you may need to cache it so that debug drawing
+appears in the correct position relative to your sprites. See the [#Troubleshooting](troubleshooting)
+section for additional details._
+
 ### Customizing Debug Drawing for Your Sprites
 
 Acetate provides several debug visualizations out-of-the-box, which are suitable for showing
@@ -457,6 +461,20 @@ If you can't activate Acetate debug mode for your app in the simulator, check th
     support for implementing `debugDraw` within your individual sprite classes. (You will, however,
     need to do your own debug drawing for anything not associated with sprites.)
 
+### Debug drawing doesn't align properly with my sprites.
+
+Acetate attempts to adjust the draw offset so that debug drawing aligns properly with your sprites.
+However, if your project adjusts the draw offset itself (via `playdate.graphics.setDrawOffset()`),
+Acetate may not have sufficient knowledge to do so correctly. In this case, provide Acetate with
+the appropriate draw offset by calling `cacheDrawOffset` from within your sprite's `draw` function:
+
+```lua
+function MySprite:draw()
+    self:cacheDrawOffset()
+    -- draw...
+end
+```
+
 ### Help, my app keeps crashing on Playdate hardware!
 
 Acetate is not initialized on-device. Attempting to access its members or call its functions outside

acetate.lua

@@ -204,6 +204,9 @@ function acetate.debugDraw()
         s = s .. acetate.focusedClass.className .. " 🔒\n"
     end
 
+    -- grab the current draw offset so we can adjust relative to it accordingly
+    local xo, yo = gfx.getDrawOffset()
+
     -- do debug drawing only if enabled
     if acetate.enabled then
 
@@ -230,7 +233,11 @@ function acetate.debugDraw()
                     gfx.pushContext()
                         -- determine the draw offset for the sprite and set useful defaults
                         local x, y = sprite:getBounds()
-                        gfx.setDrawOffset(x, y)
+                        if sprite.__ignoresDrawOffset then
+                            gfx.setDrawOffset(x, y)
+                        else
+                            gfx.setDrawOffset((sprite.__xo or (x + xo)), (sprite.__yo or (y + yo)))
+                        end
                         gfx.setLineWidth(acetate.lineWidth)
                         gfx.setColor(gfx.kColorWhite) -- white is the debug color
 
@@ -274,6 +281,7 @@ function acetate.debugDraw()
 
     -- lastly, show the debug string we've built up
     gfx.pushContext()
+        gfx.setDrawOffset(0, 0)
         gfx.setImageDrawMode(gfx.kDrawModeFillWhite)
         acetate.debugFont:drawText(s, acetate.debugStringPosition.x, acetate.debugStringPosition.y)
     gfx.popContext()

spriteExtensions.lua

@@ -60,3 +60,17 @@ function gfx.sprite:getLocalOrigin()
     local cx, cy = self:getCenter()
     return -cx * self.width, -cy * self.height
 end
+
+function gfx.sprite:cacheDrawOffset()
+    local xo, yo = gfx.getDrawOffset()
+    self.__xo = xo
+    self.__yo = yo
+end
+
+-- work around a limitation of the SDK which makes it impossible to check
+-- whether a sprite is currently set to ignore the draw offset
+local _setIgnoresDrawOffset = gfx.sprite.setIgnoresDrawOffset
+function gfx.sprite:setIgnoresDrawOffset(flag)
+    self.__ignoresDrawOffset = flag
+    _setIgnoresDrawOffset(self, flag)
+end