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/wrap_Graphics.cpp

@@ -27,6 +27,7 @@
 #include "filesystem/wrap_Filesystem.h"
 #include "video/VideoStream.h"
 #include "image/wrap_Image.h"
+#include "common/Reference.h"
 
 #include <cassert>
 #include <cstring>
@@ -60,79 +61,9 @@ int w_reset(lua_State *)
 	return 0;
 }
 
-int w_clear(lua_State *L)
+int w_present(lua_State *L)
 {
-	Colorf color;
-
-	if (lua_isnoneornil(L, 1))
-		color.set(0.0, 0.0, 0.0, 0.0);
-	else if (lua_istable(L, 1))
-	{
-		std::vector<Graphics::OptionalColorf> colors((size_t) lua_gettop(L));
-
-		for (int i = 0; i < lua_gettop(L); i++)
-		{
-			if (lua_isnoneornil(L, i + 1) || luax_objlen(L, i + 1) == 0)
-			{
-				colors[i].enabled = false;
-				continue;
-			}
-
-			for (int j = 1; j <= 4; j++)
-				lua_rawgeti(L, i + 1, j);
-
-			colors[i].enabled = true;
-			colors[i].r = (float) luaL_checknumber(L, -4);
-			colors[i].g = (float) luaL_checknumber(L, -3);
-			colors[i].b = (float) luaL_checknumber(L, -2);
-			colors[i].a = (float) luaL_optnumber(L, -1, 1.0);
-
-			lua_pop(L, 4);
-		}
-
-		luax_catchexcept(L, [&]() { instance()->clear(colors); });
-		return 0;
-	}
-	else
-	{
-		color.r = (float) luaL_checknumber(L, 1);
-		color.g = (float) luaL_checknumber(L, 2);
-		color.b = (float) luaL_checknumber(L, 3);
-		color.a = (float) luaL_optnumber(L, 4, 1.0);
-	}
-
-	luax_catchexcept(L, [&]() { instance()->clear(color); });
-	return 0;
-}
-
-int w_discard(lua_State *L)
-{
-	std::vector<bool> colorbuffers;
-
-	if (lua_istable(L, 1))
-	{
-		for (size_t i = 1; i <= luax_objlen(L, 1); i++)
-		{
-			lua_rawgeti(L, 1, i);
-			colorbuffers.push_back(luax_optboolean(L, -1, true));
-			lua_pop(L, 1);
-		}
-	}
-	else
-	{
-		bool discardcolor = luax_optboolean(L, 1, true);
-		size_t numbuffers = std::max((size_t) 1, instance()->getCanvas().size());
-		colorbuffers = std::vector<bool>(numbuffers, discardcolor);
-	}
-
-	bool stencil = luax_optboolean(L, 2, true);
-	instance()->discard(colorbuffers, stencil);
-	return 0;
-}
-
-int w_present(lua_State *)
-{
-	instance()->present();
+	luax_catchexcept(L, [&]() { instance()->present(L); });
 	return 0;
 }
 
@@ -173,6 +104,274 @@ int w_getDimensions(lua_State *L)
 	return 2;
 }
 
+int w_getPassWidth(lua_State *L)
+{
+	lua_pushinteger(L, instance()->getPassWidth());
+	return 1;
+}
+
+int w_getPassHeight(lua_State *L)
+{
+	lua_pushinteger(L, instance()->getPassHeight());
+	return 1;
+}
+
+int w_getPassDimensions(lua_State *L)
+{
+	lua_pushinteger(L, instance()->getPassWidth());
+	lua_pushinteger(L, instance()->getPassHeight());
+	return 2;
+}
+
+static int w__beginPass(lua_State *L)
+{
+	int nextstartidx = 1;
+
+	if (lua_isnoneornil(L, 1))
+	{
+		luax_catchexcept(L, [&]() { instance()->beginPass(PassInfo::BEGIN_LOAD, Colorf()); });
+		nextstartidx = 1;
+	}
+	else if (lua_isnumber(L, 1))
+	{
+		Colorf c;
+		c.r = (float) luaL_checknumber(L, 1);
+		c.g = (float) luaL_checknumber(L, 2);
+		c.b = (float) luaL_checknumber(L, 3);
+
+		if (lua_isnumber(L, 4))
+		{
+			c.a = (float) lua_tonumber(L, 4);
+			nextstartidx = 5;
+		}
+		else
+		{
+			c.a = 1.0f;
+			nextstartidx = 4;
+		}
+
+		luax_catchexcept(L, [&]() { instance()->beginPass(PassInfo::BEGIN_CLEAR, c); });
+	}
+	else if (luax_istype(L, 1, GRAPHICS_CANVAS_ID))
+	{
+		PassInfo::ColorAttachment attachment;
+		attachment.canvas = luax_checkcanvas(L, 1);
+		attachment.beginAction = PassInfo::BEGIN_LOAD;
+
+		if (lua_isnumber(L, 2))
+		{
+			attachment.beginAction = PassInfo::BEGIN_CLEAR;
+			attachment.clearColor.r = (float) luaL_checknumber(L, 2);
+			attachment.clearColor.g = (float) luaL_checknumber(L, 3);
+			attachment.clearColor.b = (float) luaL_checknumber(L, 4);
+
+			if (lua_isnumber(L, 5))
+			{
+				attachment.clearColor.a = (float) lua_tonumber(L, 5);
+				nextstartidx = 6;
+			}
+			else
+			{
+				attachment.clearColor.a = 1.0f;
+				nextstartidx = 5;
+			}
+		}
+		else
+			nextstartidx = 2;
+
+		PassInfo info;
+		info.addColorAttachment(attachment);
+
+		if (lua_isboolean(L, nextstartidx))
+		{
+			info.stencil = luax_toboolean(L, nextstartidx);
+			nextstartidx++;
+		}
+		else
+			info.stencil = false;
+
+		luax_catchexcept(L, [&]() { instance()->beginPass(info); });
+	}
+	else
+	{
+		luaL_checktype(L, 1, LUA_TTABLE);
+
+		int nattachments = std::max((int) luax_objlen(L, 1), 1);
+
+		if (nattachments > MAX_COLOR_RENDER_TARGETS)
+			return luaL_error(L, "Cannot render to %d Canvases at once!", nattachments);
+
+		PassInfo info;
+
+		for (int i = 1; i <= nattachments; i++)
+		{
+			lua_rawgeti(L, 1, i);
+			luaL_checktype(L, -1, LUA_TTABLE);
+
+			PassInfo::ColorAttachment attachment;
+			attachment.beginAction = PassInfo::BEGIN_LOAD;
+
+			lua_rawgeti(L, -1, 1);
+			attachment.canvas = luax_checkcanvas(L, -1);
+
+			lua_rawgeti(L, -2, 2);
+			if (!lua_isnoneornil(L, -1))
+			{
+				attachment.beginAction = PassInfo::BEGIN_CLEAR;
+
+				for (int j = 3; j < 6; j++)
+					lua_rawgeti(L, -j, j);
+
+				attachment.clearColor.r = (float) luaL_checknumber(L, -4);
+				attachment.clearColor.g = (float) luaL_checknumber(L, -3);
+				attachment.clearColor.b = (float) luaL_checknumber(L, -2);
+				attachment.clearColor.a = (float) luaL_optnumber(L, -1, 1.0);
+			}
+
+			lua_pop(L, 2 + (attachment.beginAction == PassInfo::BEGIN_CLEAR ? 4 : 1));
+
+			info.addColorAttachment(attachment);
+		}
+
+		info.stencil = luax_boolflag(L, 1, "stencil", false);
+
+		luax_catchexcept(L, [&]() { instance()->beginPass(info); });
+
+		nextstartidx = 2;
+	}
+
+	return nextstartidx;
+}
+
+int w_beginPass(lua_State *L)
+{
+	w__beginPass(L);
+	return 0;
+}
+
+static void screenshotCallback(love::image::ImageData *i, Reference *ref, void *gd)
+{
+	if (i != nullptr)
+	{
+		lua_State *L = (lua_State *) gd;
+		ref->push(L);
+		delete ref;
+		luax_pushtype(L, IMAGE_IMAGE_DATA_ID, i);
+		lua_call(L, 1, 0);
+	}
+	else
+		delete ref;
+}
+
+static int w__endPass(lua_State *L, int startidx)
+{
+	if (lua_isnoneornil(L, startidx))
+	{
+		luax_catchexcept(L, []() { instance()->endPass(); });
+	}
+	else
+	{
+		int x, y, w, h;
+
+		if (lua_isnumber(L, startidx))
+		{
+			x = (int) luaL_checknumber(L, 1);
+			y = (int) luaL_checknumber(L, 2);
+			w = (int) luaL_checknumber(L, 3);
+			h = (int) luaL_checknumber(L, 4);
+			startidx += 4;
+		}
+		else
+		{
+			x = 0;
+			y = 0;
+			w = instance()->getPassWidth();
+			h = instance()->getPassHeight();
+		}
+
+		luaL_checktype(L, startidx, LUA_TFUNCTION);
+
+		Graphics::ScreenshotInfo info;
+		info.callback = screenshotCallback;
+
+		lua_pushvalue(L, startidx);
+		info.ref = luax_refif(L, LUA_TFUNCTION);
+		lua_pop(L, 1);
+
+		luax_catchexcept(L,
+			[&]() { instance()->endPass(x, y, w, h, &info, L); },
+			[&](bool except) { if (except) delete info.ref; }
+		);
+	}
+
+	return 0;
+}
+
+int w_endPass(lua_State *L)
+{
+	return w__endPass(L, 1);
+}
+
+int w_renderPass(lua_State *L)
+{
+	int startidx = w__beginPass(L);
+
+	if (lua_type(L, startidx) != LUA_TFUNCTION)
+	{
+		w__endPass(L, startidx + 1);
+		luaL_checktype(L, startidx, LUA_TFUNCTION);
+		return 0;
+	}
+
+	int nargs = lua_gettop(L) - startidx;
+	int status = lua_pcall(L, nargs, 0, 0);
+
+	w__endPass(L, startidx + 1);
+
+	if (status != 0)
+		return lua_error(L);
+
+	return 0;
+}
+
+int w_isPassActive(lua_State *L)
+{
+	luax_pushboolean(L, instance()->isPassActive());
+	return 1;
+}
+
+int w_getPassCanvases(lua_State *L)
+{
+	if (!instance()->isPassActive())
+		return 0;
+
+	const PassInfo &info = instance()->getActivePass();
+
+	for (const auto &attachment : info.colorAttachments)
+		luax_pushtype(L, GRAPHICS_CANVAS_ID, attachment.canvas);
+
+	return info.colorAttachmentCount;
+}
+
+int w_captureScreenshot(lua_State *L)
+{
+	luaL_checktype(L, 1, LUA_TFUNCTION);
+
+	Graphics::ScreenshotInfo info;
+	info.callback = screenshotCallback;
+
+	lua_pushvalue(L, 1);
+	info.ref = luax_refif(L, LUA_TFUNCTION);
+	lua_pop(L, 1);
+
+	luax_catchexcept(L,
+		[&]() { instance()->captureScreenshot(info); },
+		[&](bool except) { if (except) delete info.ref; }
+	);
+
+	return 0;
+}
+
 int w_setScissor(lua_State *L)
 {
 	int nargs = lua_gettop(L);
@@ -243,13 +442,13 @@ int w_stencil(lua_State *L)
 	if (lua_toboolean(L, 4) == 0)
 		instance()->clearStencil();
 
-	instance()->drawToStencilBuffer(action, stencilvalue);
+	luax_catchexcept(L, [&](){ instance()->drawToStencilBuffer(action, stencilvalue); });
 
 	// Call stencilfunc()
 	lua_pushvalue(L, 1);
 	lua_call(L, 0, 0);
 
-	instance()->stopDrawToStencilBuffer();
+	luax_catchexcept(L, [&](){ instance()->stopDrawToStencilBuffer(); });
 	return 0;
 }
 
@@ -268,7 +467,7 @@ int w_setStencilTest(lua_State *L)
 		comparevalue = (int) luaL_checknumber(L, 2);
 	}
 
-	instance()->setStencilTest(compare, comparevalue);
+	luax_catchexcept(L, [&](){ instance()->setStencilTest(compare, comparevalue); });
 	return 0;
 }
 
@@ -1246,79 +1445,6 @@ int w_isWireframe(lua_State *L)
 	return 1;
 }
 
-int w_newScreenshot(lua_State *L)
-{
-	love::image::Image *image = luax_getmodule<love::image::Image>(L, MODULE_IMAGE_ID);
-	bool copyAlpha = luax_optboolean(L, 1, false);
-	love::image::ImageData *i = 0;
-
-	luax_catchexcept(L, [&](){ i = instance()->newScreenshot(image, copyAlpha); });
-
-	luax_pushtype(L, IMAGE_IMAGE_DATA_ID, i);
-	i->release();
-	return 1;
-}
-
-int w_setCanvas(lua_State *L)
-{
-	// Disable stencil writes.
-	instance()->stopDrawToStencilBuffer();
-
-	// called with none -> reset to default buffer
-	if (lua_isnoneornil(L, 1))
-	{
-		instance()->setCanvas();
-		return 0;
-	}
-
-	bool is_table = lua_istable(L, 1);
-	std::vector<Canvas *> canvases;
-
-	if (is_table)
-	{
-		for (int i = 1; i <= (int) luax_objlen(L, 1); i++)
-		{
-			lua_rawgeti(L, 1, i);
-			canvases.push_back(luax_checkcanvas(L, -1));
-			lua_pop(L, 1);
-		}
-	}
-	else
-	{
-		for (int i = 1; i <= lua_gettop(L); i++)
-			canvases.push_back(luax_checkcanvas(L, i));
-	}
-
-	luax_catchexcept(L, [&]() {
-		if (canvases.size() > 0)
-			instance()->setCanvas(canvases);
-		else
-			instance()->setCanvas();
-	});
-
-	return 0;
-}
-
-int w_getCanvas(lua_State *L)
-{
-	const std::vector<Canvas *> canvases = instance()->getCanvas();
-	int n = 0;
-
-	for (Canvas *c : canvases)
-	{
-		luax_pushtype(L, GRAPHICS_CANVAS_ID, c);
-		n++;
-	}
-
-	if (n == 0)
-	{
-		lua_pushnil(L);
-		n = 1;
-	}
-
-	return n;
-}
-
 int w_setShader(lua_State *L)
 {
 	if (lua_isnoneornil(L,1))
@@ -1497,8 +1623,8 @@ int w_getStats(lua_State *L)
 	lua_pushinteger(L, stats.drawCalls);
 	lua_setfield(L, -2, "drawcalls");
 
-	lua_pushinteger(L, stats.canvasSwitches);
-	lua_setfield(L, -2, "canvasswitches");
+	lua_pushinteger(L, stats.renderPasses);
+	lua_setfield(L, -2, "renderpasses");
 
 	lua_pushinteger(L, stats.shaderSwitches);
 	lua_setfield(L, -2, "shaderswitches");
@@ -1555,9 +1681,9 @@ int w_draw(lua_State *L)
 
 	luax_catchexcept(L, [&]() {
 		if (texture && quad)
-			texture->drawq(quad, m);
+			instance()->drawq(texture, quad, m);
 		else if (drawable)
-			drawable->draw(m);
+			instance()->draw(drawable, m);
 	});
 
 	return 0;
@@ -1698,11 +1824,14 @@ int w_points(lua_State *L)
 			coords[i] = luax_tofloat(L, i + 1);
 	}
 
-	instance()->points(coords, colors, numpoints);
-
-	delete[] coords;
-	if (colors)
-		delete[] colors;
+	luax_catchexcept(L,
+		[&](){ instance()->points(coords, colors, numpoints); },
+		[&](bool) {
+			delete[] coords;
+			if (colors)
+				delete[] colors;
+		}
+	);
 
 	return 0;
 }
@@ -1738,9 +1867,11 @@ int w_line(lua_State *L)
 			coords[i] = luax_tofloat(L, i + 1);
 	}
 
-	instance()->polyline(coords, args);
+	luax_catchexcept(L,
+		[&](){ instance()->polyline(coords, args); },
+		[&](bool) { delete[] coords; }
+	);
 
-	delete[] coords;
 	return 0;
 }
 
@@ -1766,11 +1897,11 @@ int w_rectangle(lua_State *L)
 	float ry = (float)luaL_optnumber(L, 7, rx);
 
 	if (lua_isnoneornil(L, 8))
-		instance()->rectangle(mode, x, y, w, h, rx, ry);
+		luax_catchexcept(L, [&](){ instance()->rectangle(mode, x, y, w, h, rx, ry); });
 	else
 	{
 		int points = (int) luaL_checknumber(L, 8);
-		instance()->rectangle(mode, x, y, w, h, rx, ry, points);
+		luax_catchexcept(L, [&](){ instance()->rectangle(mode, x, y, w, h, rx, ry, points); });
 	}
 
 	return 0;
@@ -1788,11 +1919,11 @@ int w_circle(lua_State *L)
 	float radius = (float)luaL_checknumber(L, 4);
 
 	if (lua_isnoneornil(L, 5))
-		instance()->circle(mode, x, y, radius);
+		luax_catchexcept(L, [&](){ instance()->circle(mode, x, y, radius); });
 	else
 	{
 		int points = (int) luaL_checknumber(L, 5);
-		instance()->circle(mode, x, y, radius, points);
+		luax_catchexcept(L, [&](){ instance()->circle(mode, x, y, radius, points); });
 	}
 
 	return 0;
@@ -1811,11 +1942,11 @@ int w_ellipse(lua_State *L)
 	float b = (float)luaL_optnumber(L, 5, a);
 
 	if (lua_isnoneornil(L, 6))
-		instance()->ellipse(mode, x, y, a, b);
+		luax_catchexcept(L, [&](){ instance()->ellipse(mode, x, y, a, b); });
 	else
 	{
 		int points = (int) luaL_checknumber(L, 6);
-		instance()->ellipse(mode, x, y, a, b, points);
+		luax_catchexcept(L, [&](){ instance()->ellipse(mode, x, y, a, b, points); });
 	}
 
 	return 0;
@@ -1848,11 +1979,11 @@ int w_arc(lua_State *L)
 	float angle2 = (float) luaL_checknumber(L, startidx + 4);
 
 	if (lua_isnoneornil(L, startidx + 5))
-		instance()->arc(drawmode, arcmode, x, y, radius, angle1, angle2);
+		luax_catchexcept(L, [&](){ instance()->arc(drawmode, arcmode, x, y, radius, angle1, angle2); });
 	else
 	{
 		int points = (int) luaL_checknumber(L, startidx + 5);
-		instance()->arc(drawmode, arcmode, x, y, radius, angle1, angle2, points);
+		luax_catchexcept(L, [&](){ instance()->arc(drawmode, arcmode, x, y, radius, angle1, angle2, points); });
 	}
 
 	return 0;
@@ -1900,8 +2031,11 @@ int w_polygon(lua_State *L)
 	// make a closed loop
 	coords[args]   = coords[0];
 	coords[args+1] = coords[1];
-	instance()->polygon(mode, coords, args+2);
-	delete[] coords;
+
+	luax_catchexcept(L,
+		[&](){ instance()->polygon(mode, coords, args+2); },
+		[&](bool) { delete[] coords; }
+	);
 
 	return 0;
 }
@@ -1987,8 +2121,6 @@ int w_inverseTransformPoint(lua_State *L)
 static const luaL_Reg functions[] =
 {
 	{ "reset", w_reset },
-	{ "clear", w_clear },
-	{ "discard", w_discard },
 	{ "present", w_present },
 
 	{ "newImage", w_newImage },
@@ -2030,9 +2162,6 @@ static const luaL_Reg functions[] =
 	{ "getPointSize", w_getPointSize },
 	{ "setWireframe", w_setWireframe },
 	{ "isWireframe", w_isWireframe },
-	{ "newScreenshot", w_newScreenshot },
-	{ "setCanvas", w_setCanvas },
-	{ "getCanvas", w_getCanvas },
 
 	{ "setShader", w_setShader },
 	{ "getShader", w_getShader },
@@ -2046,6 +2175,14 @@ static const luaL_Reg functions[] =
 	{ "getSystemLimits", w_getSystemLimits },
 	{ "getStats", w_getStats },
 
+	{ "beginPass", w_beginPass },
+	{ "endPass", w_endPass },
+	{ "renderPass", w_renderPass },
+	{ "isPassActive", w_isPassActive },
+	{ "getPassCanvases", w_getPassCanvases },
+
+	{ "captureScreenshot", w_captureScreenshot },
+
 	{ "draw", w_draw },
 
 	{ "print", w_print },
@@ -2057,6 +2194,9 @@ static const luaL_Reg functions[] =
 	{ "getWidth", w_getWidth },
 	{ "getHeight", w_getHeight },
 	{ "getDimensions", w_getDimensions },
+	{ "getPassWidth", w_getPassWidth },
+	{ "getPassHeight", w_getPassHeight },
+	{ "getPassDimensions", w_getPassDimensions },
 
 	{ "setScissor", w_setScissor },
 	{ "intersectScissor", w_intersectScissor },