Render pass API. Replaces love.graphics.setCanvas and friends.

- Removed love.graphics.set/getCanvas, Canvas:renderTo, Canvas:newImageData, love.graphics.clear, love.graphics.discard, and love.graphics.newScreenshot.

- Added love.graphics.beginPass and love.graphics.endPass. All rendering must happen within a pass. love.draw is now called while a render pass to the main screen is active.
- Added love.graphics.renderPass, which is a wrapper for begin/endPass which calls the supplied function argument in between a begin/end. This is similar to the old Canvas:renderTo.
- Added love.graphics.isPassActive, getPassCanvases, getPassWidth, getPassHeight, and getPassDimensions.
- Added love.graphics.captureScreenshot.

- Added a new love.run callback love.drawpasses, which is called after love.update and before love.draw. It is the place to render to Canvases using beginPass or renderPass, since love.draw now always draws to the main screen.

- Renamed the ‘canvasswitches’ field in the table returned by love.graphics.getStats to ‘renderpasses’.

love.graphics.beginPass has the following variants (and renderPass mirrors them with an additional function argument at the end):

- love.graphics.beginPass(), begins rendering to the main screen without clearing it.
- love.graphics.beginPass(r, g, b [, a]), begins rendering to the main screen and clears the screen to the specified color.

- love.graphics.beginPass(canvas [, willstencil]), begins rendering to the specified Canvas without clearing it. love.graphics.stencil can only be used within the Canvas if ‘willstencil’ is true.
- love.graphics.beginPass(canvas, r, g, b [, a] [, willstencil]), beings rendering to the specified Canvas and clears it to the specified color. love.graphics.stencil can only be used within the Canvas if ‘willstencil’ is true.

- love.graphics.beginPass(info), where ‘info’ is a table in the following form:
{
    {canvas [, r, g, b, a]}, — A canvas and an optional color to clear the Canvas to when the pass begins.
    {canvas2, [r, g, b, a]}, — Additional Canvases and optional clear colors for multi-canvas rendering.
    …,
    stencil = false, — Optional boolean field to specify whether love.graphics.stencil is allowed within this pass. False by default.
}

The pass info table can be created once up-front and used for multiple beginPass/renderPass calls.

love.graphics.endPass can take an optional callback function argument, which causes endPass to capture the contents of the Canvas drawn to in the render pass to a new ImageData and passes it to the supplied function (this replaces Canvas:newImageData). This does not work on the main screen.

love.graphics.captureScreenshot replaces love.graphics.newScreenshot. It takes a callback function argument which causes love.graphics.present to capture the contents of the screen to a new ImageData and passes it to the supplied function. captureScreenshot can only be called before drawing to the main screen begins in the current frame (e.g. in love.keypressed, love.update, etc.)

--HG--
branch : minor

src/modules/graphics/opengl/Canvas.h

@@ -82,26 +82,6 @@ public:
 	bool setWrap(const Texture::Wrap &w) override;
 	const void *getHandle() const override;
 
-	/**
-	 * @param canvases A list of other canvases to temporarily attach to this one,
-	 * to allow drawing to multiple canvases at once.
-	 **/
-	void startGrab(const std::vector<Canvas *> &canvases);
-	void startGrab();
-	void stopGrab(bool switchingToOtherCanvas = false);
-
-	/**
-	 * Create and attach a stencil buffer to this Canvas' framebuffer, if necessary.
-	 **/
-	bool checkCreateStencil();
-
-	love::image::ImageData *newImageData(love::image::Image *image, int x, int y, int w, int h);
-
-	inline const std::vector<Canvas *> &getAttachedCanvases() const
-	{
-		return attachedCanvases;
-	}
-
 	inline GLenum getStatus() const
 	{
 		return status;
@@ -117,19 +97,26 @@ public:
 		return actual_samples;
 	}
 
+	inline int getRequestedMSAA() const
+	{
+		return requested_samples;
+	}
+
+	inline ptrdiff_t getMSAAHandle() const
+	{
+		return msaa_buffer;
+	}
+
+	inline GLuint getFBO() const
+	{
+		return fbo;
+	}
+
 	static Format getSizedFormat(Format format);
 	static bool isSupported();
 	static bool isMultiFormatMultiCanvasSupported();
 	static bool isFormatSupported(Format format);
 
-	static Canvas *current;
-
-	// The viewport dimensions of the system (default) framebuffer.
-	static OpenGL::Viewport systemViewport;
-
-	// Whether the main screen should have linear -> sRGB conversions enabled.
-	static bool screenHasSRGB;
-
 	static int canvasCount;
 
 	static bool getConstant(const char *in, Format &out);
@@ -137,29 +124,20 @@ public:
 
 private:
 
-	void setupGrab();
-
-	bool createMSAAFBO(GLenum internalformat);
-	bool resolveMSAA(bool restoreprev);
-
 	void drawv(const Matrix4 &t, const Vertex *v);
 
 	static void convertFormat(Format format, GLenum &internalformat, GLenum &externalformat, GLenum &type);
 	static size_t getFormatBitsPerPixel(Format format);
 
 	GLuint fbo;
-	GLuint resolve_fbo;
 
 	GLuint texture;
 	GLuint msaa_buffer;
-	GLuint depth_stencil;
 
 	Format format;
 
 	GLenum status;
 
-	std::vector<Canvas *> attachedCanvases;
-
 	int requested_samples;
 	int actual_samples;