// MobileGL - MobileGL/MG_Impl/GLImpl/Debug/GL_Debug.cpp // Copyright (c) 2025-2026 MobileGL-Dev // Licensed under the GNU Lesser General Public License v3.0: // https://www.gnu.org/licenses/gpl-3.0.txt // https://www.gnu.org/licenses/lgpl-3.0.txt // SPDX-License-Identifier: LGPL-3.0-only // End of Source File Header #include "GL_Debug.h" #include #include #include #include #include namespace MobileGL::MG_Impl::GLImpl { namespace { // Must agree with what GL_Getter answers for GL_MAX_DEBUG_GROUP_STACK_DEPTH and // GL_MAX_DEBUG_MESSAGE_LENGTH / GL_MAX_LABEL_LENGTH; an application that sizes a buffer // off the query and then trips a different limit here would have no way to explain it. constexpr SizeT kMaxDebugGroupStackDepth = 64; constexpr GLsizei kMaxDebugMessageLength = 1024; constexpr GLsizei kMaxLabelLength = 256; // The debug state KHR_debug makes per-context. Held here rather than on GLContext because // nothing else in MobileGL reads it, and it is keyed on the context id so a // destroyed-and-recreated context starts with an empty stack and no labels - which the // unit tests, which recreate the context between cases, depend on. struct DebugState { Uint64 contextId = 0; // The messages pushed with glPushDebugGroup, innermost last. The base group GL creates // the context with is implicit and is what makes the reported depth start at 1. Vector groupStack; // Keyed by (identifier, name); see MakeObjectLabelKey. UnorderedMap objectLabels; }; DebugState& State() { static DebugState state; const Uint64 contextId = MG_State::pGLContext ? MG_State::pGLContext->GetTextureContextId() : 0; if (state.contextId != contextId) { state.contextId = contextId; state.groupStack.clear(); state.objectLabels.clear(); } return state; } Uint64 MakeObjectLabelKey(GLenum identifier, GLuint name) { return (static_cast(identifier) << 32) | static_cast(name); } void RecordDebugError(ErrorCode code, const char* caller, const String& message) { MG_State::pGLContext->RecordError(code, MakeUnique("MG_Impl/GLImpl", caller, message)); } // GL 4.6 core 20.2: only an APPLICATION or THIRD_PARTY source may be injected; the rest // are reserved for the implementation itself. Bool ValidateInjectedSource(GLenum source, const char* caller) { if (source == GL_DEBUG_SOURCE_APPLICATION || source == GL_DEBUG_SOURCE_THIRD_PARTY) { return true; } RecordDebugError(ErrorCode::InvalidEnum, caller, std::format("source {} is not GL_DEBUG_SOURCE_APPLICATION or " "GL_DEBUG_SOURCE_THIRD_PARTY.", MG_Util::ConvertGLEnumToString(source))); return false; } // A negative length means the string is NUL-terminated (GL 4.6 core 20.2), which is how // every one of these entry points spells "just use the whole thing". Bool ValidateDebugStringLength(GLsizei length, const GLchar* text, GLsizei limit, const char* caller, const char* what) { const GLsizei effective = length < 0 ? static_cast(text != nullptr ? std::strlen(text) : 0) : length; if (effective < limit) { return true; } RecordDebugError(ErrorCode::InvalidValue, caller, std::format("{} length {} is not less than the {} limit of {}.", what, effective, what, limit)); return false; } String MakeDebugString(GLsizei length, const GLchar* text) { if (text == nullptr) return {}; return length < 0 ? String(text) : String(text, static_cast(length)); } // Whether `name` currently names an object of `identifier`'s type. GL 4.6 core 20.5 makes // labelling something that does not exist INVALID_VALUE, and every type KHR_debug lists // has a frontend name check - so this is answered exactly rather than waved through. // GL_DISPLAY_LIST is deliberately absent: it exists only in the compatibility profile, // which MobileGL does not expose, so it falls to the INVALID_ENUM path below. Bool ValidateLabelledObject(GLenum identifier, GLuint name, Bool& outIdentifierKnown) { outIdentifierKnown = true; auto* context = MG_State::pGLContext.get(); switch (identifier) { case GL_BUFFER: return context->ValidateBufferName(name); case GL_SHADER: return context->ValidateShaderName(name); case GL_PROGRAM: return context->ValidateProgramName(name); case GL_VERTEX_ARRAY: return context->ValidateVertexArrayName(name); case GL_QUERY: return IsQuery(name) == GL_TRUE; case GL_PROGRAM_PIPELINE: return context->ValidateProgramPipelineName(name); case GL_TRANSFORM_FEEDBACK: return context->ValidateTransformFeedbackName(name); case GL_SAMPLER: return context->ValidateSamplerName(name); case GL_TEXTURE: return context->ValidateTextureName(name); case GL_RENDERBUFFER: return context->ValidateRenderbufferName(name); case GL_FRAMEBUFFER: // Name 0 is the default framebuffer, which is a real, labellable object. return name == 0 || context->ValidateFramebufferName(name); default: outIdentifierKnown = false; return false; } } } // namespace GLint GetDebugGroupStackDepth() { // GL 4.6 core 20.6: the context is created with one group already on the stack, so the // reported depth is one more than the number of pushes the application has made. return static_cast(State().groupStack.size()) + 1; } void PushDebugGroup(GLenum source, GLuint id, GLsizei length, const GLchar* message) { static_cast(id); if (!ValidateInjectedSource(source, __func__)) return; if (!ValidateDebugStringLength(length, message, kMaxDebugMessageLength, __func__, "message")) return; auto& state = State(); if (state.groupStack.size() + 1 >= kMaxDebugGroupStackDepth) { // Not INVALID_*: KHR_debug gives the group stack its own error code. RecordDebugError(ErrorCode::StackOverflow, __func__, std::format("the debug group stack is already {} deep, which is its maximum.", kMaxDebugGroupStackDepth)); return; } state.groupStack.push_back(MakeDebugString(length, message)); MGLOG_D("glPushDebugGroup(%s) -> depth %d", state.groupStack.back().c_str(), GetDebugGroupStackDepth()); } void PopDebugGroup() { auto& state = State(); if (state.groupStack.empty()) { // The base group the context was created with may not be popped (GL 4.6 core 20.6). RecordDebugError(ErrorCode::StackUnderflow, __func__, "the debug group stack holds only the group the context was created with."); return; } MGLOG_D("glPopDebugGroup(%s)", state.groupStack.back().c_str()); state.groupStack.pop_back(); } void DebugMessageInsert(GLenum source, GLenum type, GLuint id, GLenum severity, GLsizei length, const GLchar* buf) { static_cast(id); if (!ValidateInjectedSource(source, __func__)) return; switch (type) { case GL_DEBUG_TYPE_ERROR: case GL_DEBUG_TYPE_DEPRECATED_BEHAVIOR: case GL_DEBUG_TYPE_UNDEFINED_BEHAVIOR: case GL_DEBUG_TYPE_PORTABILITY: case GL_DEBUG_TYPE_PERFORMANCE: case GL_DEBUG_TYPE_MARKER: case GL_DEBUG_TYPE_PUSH_GROUP: case GL_DEBUG_TYPE_POP_GROUP: case GL_DEBUG_TYPE_OTHER: break; default: RecordDebugError(ErrorCode::InvalidEnum, __func__, std::format("type {} is not a debug message type.", MG_Util::ConvertGLEnumToString(type))); return; } switch (severity) { case GL_DEBUG_SEVERITY_HIGH: case GL_DEBUG_SEVERITY_MEDIUM: case GL_DEBUG_SEVERITY_LOW: case GL_DEBUG_SEVERITY_NOTIFICATION: break; default: RecordDebugError(ErrorCode::InvalidEnum, __func__, std::format("severity {} is not a debug message severity.", MG_Util::ConvertGLEnumToString(severity))); return; } if (!ValidateDebugStringLength(length, buf, kMaxDebugMessageLength, __func__, "message")) return; // No callback is ever invoked and the message log is empty by construction // (GL_MAX_DEBUG_LOGGED_MESSAGES is 1 and glGetDebugMessageLog returns nothing), so the // application-visible effect is exactly the error checking above. The text still reaches // MobileGL's own log, where it is worth having next to the calls it annotates - at debug // level, so an application that inserts a message per draw costs nothing in a release build. MGLOG_D("glDebugMessageInsert: %s", MakeDebugString(length, buf).c_str()); } void ObjectLabel(GLenum identifier, GLuint name, GLsizei length, const GLchar* label) { Bool identifierKnown = false; const Bool objectExists = ValidateLabelledObject(identifier, name, identifierKnown); if (!identifierKnown) { RecordDebugError(ErrorCode::InvalidEnum, __func__, std::format("identifier {} is not a labellable object type.", MG_Util::ConvertGLEnumToString(identifier))); return; } if (!objectExists) { RecordDebugError(ErrorCode::InvalidValue, __func__, std::format("{} {} is not the name of an existing object.", MG_Util::ConvertGLEnumToString(identifier), name)); return; } if (!ValidateDebugStringLength(length, label, kMaxLabelLength, __func__, "label")) return; auto& labels = State().objectLabels; const Uint64 key = MakeObjectLabelKey(identifier, name); if (label == nullptr) { // GL 4.6 core 20.5: a NULL label removes any label the object had. labels.erase(key); return; } labels[key] = MakeDebugString(length, label); } void GetObjectLabel(GLenum identifier, GLuint name, GLsizei bufSize, GLsizei* length, GLchar* label) { if (bufSize < 0) { RecordDebugError(ErrorCode::InvalidValue, __func__, "bufSize must not be negative."); return; } Bool identifierKnown = false; const Bool objectExists = ValidateLabelledObject(identifier, name, identifierKnown); if (!identifierKnown) { RecordDebugError(ErrorCode::InvalidEnum, __func__, std::format("identifier {} is not a labellable object type.", MG_Util::ConvertGLEnumToString(identifier))); return; } if (!objectExists) { RecordDebugError(ErrorCode::InvalidValue, __func__, std::format("{} {} is not the name of an existing object.", MG_Util::ConvertGLEnumToString(identifier), name)); return; } const auto& labels = State().objectLabels; const auto it = labels.find(MakeObjectLabelKey(identifier, name)); const String& text = it != labels.end() ? it->second : String{}; // GL 4.6 core 20.5: the returned length excludes the NUL, and an unlabelled object hands // back an empty string with length 0 rather than an error. SizeT copied = 0; if (label != nullptr && bufSize > 0) { copied = std::min(text.size(), static_cast(bufSize) - 1); std::memcpy(label, text.data(), copied); label[copied] = '\0'; } if (length != nullptr) { *length = static_cast(copied); } } } // namespace MobileGL::MG_Impl::GLImpl