Allow adding debug annotations to OpenGL objects. (#1930)

* Allow adding debug annotations to OpenGL objects, as well as defining GPU zones to achieve functionality very similar to Tracy, but on the GPU. V2
---------

Co-authored-by: sprunk <[email protected]>

Author: lhog

rts/Lua/LuaConstGL.cpp

@@ -704,9 +704,37 @@ bool LuaConstGL::PushEntries(lua_State* L)
 	PUSH_GL(STENCIL_ATTACHMENT_EXT);
 
 	return true;
+
+	/******************************************************************************
+	 * OpenGL Object Types
+	 * @section objecttypes
+	******************************************************************************/
+
+	/// @field GL_BUFFER 0x82E0
+	PUSH_GL(BUFFER);
+	/// @field GL_SHADER 0x82E1
+	PUSH_GL(SHADER);
+	/// @field GL_PROGRAM 0x82E2
+	PUSH_GL(PROGRAM);
+	/// @field GL_VERTEX_ARRAY 0x8074
+	PUSH_GL(VERTEX_ARRAY);
+	/// @field GL_QUERY 0x82E3
+	PUSH_GL(QUERY);
+	/// @field GL_PROGRAM_PIPELINE 0x82E4
+	PUSH_GL(PROGRAM_PIPELINE);
+	/// @field GL_TRANSFORM_FEEDBACK 0x8E22
+	PUSH_GL(TRANSFORM_FEEDBACK);
+	/// @field GL_RENDERBUFFER 0x8D41
+	PUSH_GL(RENDERBUFFER);
+	/// @field GL_FRAMEBUFFER 0x8D40
+	PUSH_GL(FRAMEBUFFER);
+
+	return true;
 }
 
 
+
+
 /******************************************************************************
  * Not included, but useful texture Formats
  * @section textureformats

rts/Lua/LuaOpenGL.cpp

@@ -470,6 +470,12 @@ bool LuaOpenGL::PushEntries(lua_State* L)
 	REGISTER_LUA_CFUNC(GetWaterRendering);
 	REGISTER_LUA_CFUNC(GetMapRendering);
 
+	if (GLAD_GL_KHR_debug) {
+		REGISTER_LUA_CFUNC(ObjectLabel);
+		REGISTER_LUA_CFUNC(PushDebugGroup);
+		REGISTER_LUA_CFUNC(PopDebugGroup);
+	}
+
 	if (canUseShaders)
 		LuaShaders::PushEntries(L);
 
@@ -5667,5 +5673,78 @@ int LuaOpenGL::GetMapRendering(lua_State* L)
 	return 0;
 }
 
+/**
+ * @function gl.ObjectLabel labels an object for use with debugging tools
+ * @param objectTypeIdentifier GLenum Specifies the type of object being labeled.
+ * @param objectID GLuint Specifies the name or ID of the object to label.
+ * @param label string A string containing the label to be assigned to the object.
+ * @return nil
+ */
+int LuaOpenGL::ObjectLabel(lua_State* L) {
+	const auto identifier = static_cast<GLenum>(luaL_checkinteger(L, 1));
+
+	switch (identifier) {
+	case GL_BUFFER: [[fallthrough]];
+	case GL_SHADER: [[fallthrough]];
+	case GL_PROGRAM: [[fallthrough]];
+	case GL_VERTEX_ARRAY: [[fallthrough]];
+	case GL_QUERY: [[fallthrough]];
+	case GL_PROGRAM_PIPELINE: [[fallthrough]];
+	case GL_TRANSFORM_FEEDBACK: [[fallthrough]];
+	case GL_TEXTURE: [[fallthrough]];
+	case GL_RENDERBUFFER: [[fallthrough]];
+	case GL_FRAMEBUFFER:
+		break;
+	default: {  // something else
+		LOG_L(L_ERROR, "gl.%s: invalid identifier (%u)", __func__, identifier);
+		return 0;
+	}
+	}
+
+	const auto objectID = static_cast<GLuint>(luaL_checkinteger(L, 2));
+	const auto* label = luaL_checkstring(L, 3);
+	glObjectLabel(identifier, objectID, -1, label);
+
+	return 0;
+}
+
+// https://registry.khronos.org/OpenGL-Refpages/gl4/html/glPushDebugGroup.xhtml
+/**
+ * @function gl.PushDebugGroup pushes a debug marker for nVidia nSight 2024.04, does not seem to work when FBO's are raw bound
+ * @param id GLuint A numeric identifier for the group.
+ * @param message string A human-readable string describing the debug group.
+ * @param sourceIsThirdParty boolean Set the source tag, true for GL_DEBUG_SOURCE_THIRD_PARTY, false for GL_DEBUG_SOURCE_APPLICATION. default false
+ * @return nil
+ */
+int LuaOpenGL::PushDebugGroup(lua_State* L) {
+	const auto id = static_cast<GLuint>(luaL_checkinteger(L, 1));
+	std::string message = luaL_checkstring(L, 2);
+	const bool sourceIsThirdParty = luaL_optboolean(L, 3, false);
+
+	GLint maxLength = 0;
+	glGetIntegerv(GL_MAX_DEBUG_MESSAGE_LENGTH, &maxLength);
+	if (maxLength <= 0)
+		return 0;
+
+	if (message.length() >= maxLength) {
+		static constexpr std::string_view TRIM = "(...)";
+		message.resize(maxLength - TRIM.length() - 1);
+		message += TRIM;
+		assert(message.length() < maxLength);
+	}
+
+	glPushDebugGroup((sourceIsThirdParty ? GL_DEBUG_SOURCE_THIRD_PARTY : GL_DEBUG_SOURCE_APPLICATION), id, -1, message.c_str());
+	return 0;
+}
+
+/**
+ * @function gl.PopDebugGroup
+ * @return nil
+ */
+int LuaOpenGL::PopDebugGroup(lua_State* L) {
+	glPopDebugGroup();
+	return 0;
+}
+
 /******************************************************************************/
 /******************************************************************************/

rts/Lua/LuaOpenGL.h

@@ -353,6 +353,10 @@ class LuaOpenGL {
 		static int GetSun(lua_State* L);
 		static int GetWaterRendering(lua_State* L);
 		static int GetMapRendering(lua_State* L);
+
+		static int ObjectLabel(lua_State* L);
+		static int PushDebugGroup(lua_State* L);
+		static int PopDebugGroup(lua_State* L);
 };
 
 inline void LuaOpenGL::InitMatrixState(lua_State* L, const char* fn) {

rts/Lua/LuaShaders.cpp

@@ -780,7 +780,9 @@ int LuaShaders::CreateShader(lua_State* L)
 
 	// note: index, not raw ID
 	lua_pushnumber(L, shaders.AddProgram(p));
-	return 1;
+	// also push the program ID
+	lua_pushnumber(L, prog);
+	return 2;
 }
 
 

rts/Lua/LuaVBO.cpp

@@ -63,7 +63,8 @@ bool LuaVBOs::PushEntries(lua_State* L)
 		"UnbindBufferRange", &LuaVBOImpl::UnbindBufferRange,
 
 		"DumpDefinition", &LuaVBOImpl::DumpDefinition,
-		"GetBufferSize", &LuaVBOImpl::GetBufferSize
+		"GetBufferSize", &LuaVBOImpl::GetBufferSize,
+		"GetID", & LuaVBOImpl::GetID
 	);
 
 	gl.set("VBO", sol::lua_nil); // don't want this to be accessible directly without gl.GetVBO

rts/Lua/LuaVBOImpl.cpp

@@ -1486,6 +1486,17 @@ void LuaVBOImpl::DumpDefinition()
 	LOG("%s", ss.str().c_str());
 }
 
+/*** Gets the OpenGL Buffer ID
+ *
+ * @function VBO:GetID
+ * @return number bufferID
+ */
+uint32_t LuaVBOImpl::GetID() const
+{
+	VBOExistenceCheck(vbo, __func__);
+	return vbo->GetId();
+}
+
 void LuaVBOImpl::AllocGLBuffer(size_t byteSize)
 {
 	if (defTarget == GL_UNIFORM_BUFFER && bufferSizeInBytes > UBO_SAFE_SIZE_BYTES) {

rts/Lua/LuaVBOImpl.h

@@ -52,6 +52,7 @@ class LuaVBOImpl {
 	int UnbindBufferRange(const GLuint index, const sol::optional<int> elemOffsetOpt, const sol::optional<int> elemCountOpt, const sol::optional<GLenum> targetOpt);
 
 	void DumpDefinition();
+	uint32_t GetID() const;
 public:
 	static bool Supported(GLenum target);
 private: