enhancement: ability to retain a canvas between push cycle

README.md

@@ -119,6 +119,12 @@ push:setupCanvas(canvasList)
 --e.g. push:setupCanvas({   { name = "foreground", shader = foregroundShader }, { name = "background" }   })
 ```
 
+Table parameters are:
+- **name** (string): name of canvas
+- **shader** (shader): shader to be used when drawing canvas
+- **stencil** (bool): canvas uses stencil
+- **retain** (bool): do not clear canvas in push:finish()
+
 Shaders can be passed to canvases directly through push:setupCanvas(), or you can choose to set them later.
 ```lua
 push:setShader(canvasName, shader)

examples/canvases-retain/init.lua

@@ -0,0 +1,47 @@
+--[[ Multiple canvases and shaders ]]--
+
+return function ()
+
+  love.graphics.setDefaultFilter("linear", "linear") --default filter
+
+  local gameWidth, gameHeight = 800, 600
+
+  local windowWidth, windowHeight = love.window.getDesktopDimensions()
+  windowWidth, windowHeight = windowWidth*.5, windowHeight*.5
+
+  push:setupScreen(gameWidth, gameHeight, windowWidth, windowHeight, {
+    fullscreen = false,
+    resizable = true,
+    highdpi = true,
+    canvas = true
+  })
+
+  time = 0
+
+  function love.load()
+    push:setupCanvas({
+      { name = "main" },
+      { name = "retained", retain = true }  --canvas will not be cleared by push.finish()
+    })
+  end
+
+  local canvasRendered = false
+
+  function love.update(dt)
+    if not canvasRendered then
+      push:setCanvas("retained")
+      love.graphics.rectangle("fill", 25, 25, 105, 100)
+      push:setCanvas("main")
+      canvasRendered = true
+    end
+  end
+
+  function love.draw()
+    push:start()
+    push:setCanvas("main")
+    love.graphics.rectangle('fill', 25, 130, 50, 50)
+    love.graphics.rectangle('fill', 80, 130, 50, 50)
+    push:finish()
+  end
+
+end

push.lua

@@ -85,7 +85,8 @@ function push:addCanvas(params)
     private = params.private,
     shader = params.shader,
     canvas = love.graphics.newCanvas(self._WWIDTH, self._WHEIGHT),
-    stencil = params.stencil or self._stencil
+    stencil = params.stencil or self._stencil,
+    retain = params.retain
   })
 end
 
@@ -214,8 +215,10 @@ function push:finish(shader)
 
     --clear canvas
     for i = 1, #self.canvases do
-      love.graphics.setCanvas(self.canvases[i].canvas)
-      love.graphics.clear()
+        if not self.canvases[i].retain then
+            love.graphics.setCanvas(self.canvases[i].canvas)
+            love.graphics.clear()
+        end
     end
 
     love.graphics.setCanvas()