[Test] (MG_IntegrationTest): pin the two shipped memo bugs with rendered pixels

Both d7976326 bugs passed every unit test while corrupting real frames -
state-level assertions cannot see them. This module renders and reads
back.

A headless EGL-pbuffer harness (no window, no GLFW) linking MobileGL_s
directly, registered once per backend under the ctest label
integration-gpu, behind the default-OFF option
MOBILEGL_BUILD_INTEGRATION_TEST. The platform pre-flight runs the ENTIRE
bring-up in a forked child first - MobileGL aborts rather than returning
errors on an unusable platform, and the child dying on any signal turns
into a clean GTEST_SKIP instead of taking the test binary down.
MOBILEGL_ITEST_REQUIRE_GPU makes the label falsifiable: with it set, an
unusable harness (or a context that lands on a software rasterizer) is a
FAILURE - without it, a CI runner whose driver pinning silently broke
reports the same green as one that rendered every frame. Configure-time
detection pins the EGL vendor and Vulkan ICD jsons, preferring hardware
vendors and never selecting llvmpipe/lavapipe.

Scenarios assert on glReadPixels with whole-region pixel counts (a
2x2 quadrant pattern whose signature distinguishes all eight square
symmetries; every region predicate reports the first offending pixel):
- OrientationScenario: default -> FBO -> default, pinning the
  transform-flags memo key. Keying GetBaseTransformFlagsRaw on the
  pre-transform alone fails exactly 3 entries.
- StreamedArenaScenario: an untouched streamed vertex buffer must
  survive transient-arena recycling. Re-enabling only the cross-frame
  vertex revalidation fails exactly this entry.
- CrossFrameBufferScenario + ResidentIndexScenario: cross-frame
  mutation matrix (SubData, map/unmap, persistent+flush, coherent
  persistent, orphan, CopyBufferSubData; vertex and index) plus six
  adversarial resident-EBO constructions. Instrumentation showed the
  cross-frame EBO memo cannot be made to serve wrong bytes from GL
  level on this stack (89 entries, 81 accepts, zero divergent slices) -
  these cases are freshness tripwires, documented as such in-file; the
  EBO half of d7976326 remains unpinned by a failing test.

At the buggy commit 72ee7c43 the suite fails 4 entries (3 orientation +
1 streamed-arena); at d7976326 all 52 pass, 5 consecutive runs, zero
flakes, and the default build is bit-for-bit unaffected (unit suite
unchanged). Adversarially verified twice, including hostile-platform
sweeps (26 configurations, all clean skips) and hand-edits of each
production hole in isolation.
This commit is contained in:
BZLZHH
2026-08-07 03:30:18 -04:00
parent d7976326fa
commit 313b75a7c0
10 changed files with 2768 additions and 0 deletions
@@ -0,0 +1,587 @@
// MobileGL - MobileGL/MG_IntegrationTest/Harness/HeadlessGL.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 "HeadlessGL.h"
#include <algorithm>
#include <cstdio>
#include <cstdlib>
#include <cstring>
#include <ostream>
#include <sstream>
// MobileGL's own headers, in the order MobileGL/Includes.h uses them: GL/gl.h
// first, then glcorearb.h for the 3.x+ entry points. This binary links
// MobileGL_s, so every gl*/egl* below binds to MobileGL's implementation, not
// to a system loader.
#ifdef GLAPI
#undef GLAPI
#endif
#include <EGL/egl.h>
#define GL_GLEXT_PROTOTYPES
#include <GL/gl.h>
#include <GL/glcorearb.h>
#undef GL_GLEXT_PROTOTYPES
// The pre-flight below runs the whole EGL bring-up in a forked child, which is
// the only construction that is actually predictive here: MobileGL ABORTS
// (MOBILEGL_ASSERT -> SIGTRAP) rather than returning an error on an unusable
// platform, so nothing the parent can call in-process is allowed to be wrong.
#if !defined(_WIN32) && !defined(__APPLE__) && __has_include(<sys/wait.h>)
#define MGITEST_HAVE_FORK_PREFLIGHT 1
#include <csignal>
#include <ctime>
#include <sys/resource.h>
#include <sys/types.h>
#include <sys/wait.h>
#include <unistd.h>
#else
#define MGITEST_HAVE_FORK_PREFLIGHT 0
#endif
namespace MGITest {
namespace {
// Small enough that a readback is cheap, big enough that "top third" and
// "bottom third" are unambiguous. Non-square on purpose: a transposing
// bug cannot hide behind a square.
constexpr int kSurfaceWidth = 128;
constexpr int kSurfaceHeight = 96;
std::string EnvOr(const char* name, const char* fallback) {
const char* value = std::getenv(name);
return (value != nullptr && value[0] != '\0') ? std::string(value) : std::string(fallback);
}
// A skip reason is only useful if it says which call failed AND why, so
// every bring-up step reports the EGL error it left behind.
std::string WithEglError(const char* what) {
std::ostringstream out;
out << what << " (eglGetError=0x" << std::hex << eglGetError() << ")";
return out.str();
}
// The EGL objects one bring-up produces.
struct EglBringUp {
void* display = nullptr;
void* surface = nullptr;
void* context = nullptr;
std::string renderer;
};
// THE bring-up, in one function so the pre-flight child and the parent run
// literally the same sequence - a pre-flight that tests something narrower
// than what the parent will do is exactly the kind of "predictive" check
// that is not.
//
// Returns 0 on success, or the 1-based index of the step that failed, and
// fills outReason either way.
int RunEglBringUp(EglBringUp& out, std::string& outReason) {
EGLDisplay display = eglGetDisplay(EGL_DEFAULT_DISPLAY);
if (display == EGL_NO_DISPLAY) {
outReason = WithEglError("eglGetDisplay(EGL_DEFAULT_DISPLAY) returned EGL_NO_DISPLAY");
return 1;
}
EGLint major = 0, minor = 0;
if (eglInitialize(display, &major, &minor) != EGL_TRUE) {
outReason = WithEglError("eglInitialize failed: no usable display/driver on this machine");
return 2;
}
if (eglBindAPI(EGL_OPENGL_API) != EGL_TRUE) {
outReason = WithEglError("eglBindAPI(EGL_OPENGL_API) failed");
return 3;
}
const EGLint configAttribs[] = {EGL_SURFACE_TYPE,
EGL_PBUFFER_BIT,
EGL_RED_SIZE,
8,
EGL_GREEN_SIZE,
8,
EGL_BLUE_SIZE,
8,
EGL_ALPHA_SIZE,
8,
EGL_DEPTH_SIZE,
24,
EGL_RENDERABLE_TYPE,
EGL_OPENGL_BIT,
EGL_NONE};
EGLConfig config = nullptr;
EGLint configCount = 0;
if (eglChooseConfig(display, configAttribs, &config, 1, &configCount) != EGL_TRUE || configCount < 1) {
outReason = WithEglError("eglChooseConfig found no pbuffer-capable RGBA8/D24 config");
return 4;
}
const EGLint contextAttribs[] = {EGL_CONTEXT_MAJOR_VERSION, 3, EGL_CONTEXT_MINOR_VERSION, 3, EGL_NONE};
EGLContext context = eglCreateContext(display, config, EGL_NO_CONTEXT, contextAttribs);
if (context == EGL_NO_CONTEXT) {
context = eglCreateContext(display, config, EGL_NO_CONTEXT, nullptr);
}
if (context == EGL_NO_CONTEXT) {
outReason = WithEglError("eglCreateContext failed: no desktop-GL context available");
return 5;
}
const EGLint pbufferAttribs[] = {EGL_WIDTH, kSurfaceWidth, EGL_HEIGHT, kSurfaceHeight, EGL_NONE};
EGLSurface surface = eglCreatePbufferSurface(display, config, pbufferAttribs);
if (surface == EGL_NO_SURFACE) {
outReason = WithEglError("eglCreatePbufferSurface failed");
return 6;
}
// The step that brings the whole backend up (DirectVulkan creates its
// instance, device and surface in here) and therefore the step that
// aborts instead of returning an error on an unusable platform.
if (eglMakeCurrent(display, surface, surface, context) != EGL_TRUE) {
outReason = WithEglError("eglMakeCurrent failed");
return 7;
}
const GLubyte* renderer = glGetString(GL_RENDERER);
if (renderer == nullptr) {
outReason = "glGetString(GL_RENDERER) returned null after eglMakeCurrent";
return 8;
}
out.display = display;
out.surface = surface;
out.context = context;
out.renderer = reinterpret_cast<const char*>(renderer);
outReason.clear();
return 0;
}
// Platform pre-flight, and the reason this module can claim to skip
// cleanly rather than merely hope to.
//
// MobileGL does not return errors when the platform is unusable - it
// ABORTS. MOBILEGL_ASSERT raises SIGTRAP, and the DirectVulkan bring-up
// asserts its way through instance, physical-device and surface creation
// inside eglMakeCurrent. So there is no in-process question the harness
// can ask that is guaranteed to be survivable, and the old form (dlopen
// the Vulkan loader, count physical devices, look for
// VK_EXT_headless_surface) was a guess at the abort conditions rather
// than a test of them: it named three of the ways bring-up can die and
// was silent about every other one, including every DirectGLES one.
//
// What is actually predictive is to run the bring-up itself somewhere a
// SIGTRAP is a datum instead of a crash. fork() gives exactly that: the
// child performs the identical sequence and _exit(0)s on success, and
// ANY non-zero exit or ANY signal in the parent's waitpid() means "this
// platform is unusable" - whatever the reason, including reasons nobody
// has thought of. Only then does the parent do the real bring-up.
//
// Returns an empty string when the platform survived a full bring-up.
std::string PreflightBringUp() {
#if !MGITEST_HAVE_FORK_PREFLIGHT
// No fork(): let the in-process bring-up speak for itself, which is
// what this module did before. Windows/macOS are not CI targets for
// the headless scenarios.
return {};
#else
int channel[2] = {-1, -1};
if (pipe(channel) != 0) {
return {}; // cannot pre-flight; fall through to the in-process attempt
}
// The child inherits our stdio buffers; flush so nothing is printed twice.
std::fflush(nullptr);
const pid_t child = fork();
if (child < 0) {
close(channel[0]);
close(channel[1]);
return {};
}
if (child == 0) {
close(channel[0]);
// The child is EXPECTED to die on a signal on an unusable
// platform; that is the measurement. Do not let each such
// measurement drop a core file next to the test binary.
const rlimit noCore{0, 0};
setrlimit(RLIMIT_CORE, &noCore);
std::fprintf(stderr, "[itest] pre-flight child: attempting a full EGL bring-up\n");
EglBringUp local;
std::string reason;
const int step = RunEglBringUp(local, reason);
if (!reason.empty()) {
const std::size_t bytes = std::min<std::size_t>(reason.size(), 480);
const ssize_t written = write(channel[1], reason.data(), bytes);
(void)written;
}
close(channel[1]);
// _exit, never exit(): every atexit handler and static destructor
// in this address space belongs to the parent's copy of the world,
// and the child is holding a live context it must not tear down.
_exit(step);
}
close(channel[1]);
// Reap first, read after: the message is bounded well below the pipe
// buffer so the child can never block writing it, and polling the exit
// status is what lets a wedged child be killed instead of hanging the
// parent on a read that will never return.
constexpr int kPreflightTimeoutMs = 30000;
int status = 0;
int waitedMs = 0;
for (;;) {
const pid_t reaped = waitpid(child, &status, WNOHANG);
if (reaped == child) break;
if (reaped < 0) {
close(channel[0]);
return "waitpid on the EGL bring-up pre-flight child failed";
}
if (waitedMs >= kPreflightTimeoutMs) {
kill(child, SIGKILL);
(void)waitpid(child, &status, 0);
close(channel[0]);
std::ostringstream out;
out << "the EGL bring-up wedged: a forked pre-flight child made no progress in "
<< kPreflightTimeoutMs / 1000 << "s and was killed";
return out.str();
}
timespec nap{0, 10 * 1000 * 1000};
nanosleep(&nap, nullptr);
waitedMs += 10;
}
std::string childSays;
char buffer[512];
for (;;) {
const ssize_t got = read(channel[0], buffer, sizeof(buffer));
if (got <= 0) break;
childSays.append(buffer, static_cast<std::size_t>(got));
}
close(channel[0]);
if (WIFSIGNALED(status)) {
const int signalNumber = WTERMSIG(status);
const char* signalName = strsignal(signalNumber);
std::ostringstream out;
out << "the EGL bring-up ABORTS on this platform: a forked pre-flight child died on signal "
<< signalNumber << " (" << (signalName != nullptr ? signalName : "?") << ")";
if (!childSays.empty()) out << " after: " << childSays;
out << ". MobileGL asserts rather than returning an error here, so the scenarios would "
"have taken the whole test binary down with them";
return out.str();
}
if (!WIFEXITED(status)) {
return "the EGL bring-up pre-flight child neither exited nor was signalled";
}
const int exitStatus = WEXITSTATUS(status);
if (exitStatus != 0) {
std::ostringstream out;
out << (childSays.empty() ? "the EGL bring-up failed" : childSays)
<< " (forked pre-flight child exit status " << exitStatus << ")";
return out.str();
}
return {};
#endif
}
} // namespace
bool RequireGpu() {
const char* value = std::getenv("MOBILEGL_ITEST_REQUIRE_GPU");
return value != nullptr && value[0] != '\0' && std::strcmp(value, "0") != 0;
}
std::ostream& operator<<(std::ostream& os, const Rgba8& c) {
os << "rgba(" << int(c.r) << "," << int(c.g) << "," << int(c.b) << "," << int(c.a) << ")";
return os;
}
Rgba8 Image::At(int x, int y) const {
if (x < 0 || y < 0 || x >= m_width || y >= m_height) {
return Rgba8{};
}
const std::size_t index = (static_cast<std::size_t>(y) * m_width + x) * 4;
return Rgba8{m_pixels[index], m_pixels[index + 1], m_pixels[index + 2], m_pixels[index + 3]};
}
const char* Image::ColorName(int x, int y) const {
const Rgba8 c = At(x, y);
const bool r = c.r > 160, g = c.g > 160, b = c.b > 160;
const bool nr = c.r < 96, ng = c.g < 96, nb = c.b < 96;
if (nr && ng && nb) return "black";
if (r && g && b) return "white";
if (r && ng && nb) return "red";
if (nr && g && nb) return "green";
if (nr && ng && b) return "blue";
if (r && g && nb) return "yellow";
return "other";
}
std::size_t Image::ByteDiffCount(const Image& other) const {
if (m_width != other.m_width || m_height != other.m_height) {
return std::max(m_pixels.size(), other.m_pixels.size());
}
std::size_t differing = 0;
for (std::size_t i = 0; i < m_pixels.size(); ++i) {
if (m_pixels[i] != other.m_pixels[i]) ++differing;
}
return differing;
}
std::string Image::QuadrantSignature() const {
if (m_width < 2 || m_height < 2) return "<empty>";
// Quadrant CENTRES, so a one-pixel rounding difference at a quadrant edge
// never decides the answer. Order is fixed and load-bearing: bottom-left,
// bottom-right, top-left, top-right.
const int leftX = m_width / 4;
const int rightX = m_width * 3 / 4;
const int bottomY = m_height / 4;
const int topY = m_height * 3 / 4;
std::ostringstream out;
out << ColorName(leftX, bottomY) << "," << ColorName(rightX, bottomY) << "," << ColorName(leftX, topY) << ","
<< ColorName(rightX, topY);
return out.str();
}
RegionScan ScanRegion(const Image& image, int x0, int x1, int y0, int y1, const char* expectedColor) {
RegionScan scan;
x0 = std::max(x0, 0);
y0 = std::max(y0, 0);
x1 = std::min(x1, image.Width() - 1);
y1 = std::min(y1, image.Height() - 1);
for (int y = y0; y <= y1; ++y) {
for (int x = x0; x <= x1; ++x) {
++scan.total;
const char* name = image.ColorName(x, y);
if (std::strcmp(name, expectedColor) == 0) continue;
++scan.offenders;
if (scan.firstX < 0) {
scan.firstX = x;
scan.firstY = y;
scan.firstColor = image.At(x, y);
scan.firstColorName = name;
}
}
}
return scan;
}
::testing::AssertionResult RegionIsMostly(const Image& image, int x0, int x1, int y0, int y1,
const char* expectedColor, double tolerance,
const std::string& when) {
const RegionScan scan = ScanRegion(image, x0, x1, y0, y1, expectedColor);
if (scan.total == 0) {
return ::testing::AssertionFailure()
<< when << ": region x[" << x0 << "," << x1 << "] y[" << y0 << "," << y1
<< "] is empty against a " << image.Width() << "x" << image.Height() << " readback";
}
const double offendingFraction = static_cast<double>(scan.offenders) / scan.total;
if (offendingFraction <= tolerance) {
return ::testing::AssertionSuccess();
}
return ::testing::AssertionFailure()
<< when << ": region x[" << x0 << "," << x1 << "] y[" << y0 << "," << y1 << "] should be all "
<< expectedColor << ", but " << scan.offenders << " of " << scan.total << " pixels ("
<< static_cast<int>(offendingFraction * 100.0 + 0.5) << "%) are not; first offender at (" << scan.firstX
<< "," << scan.firstY << ") is " << scan.firstColorName << " " << scan.firstColor;
}
HeadlessGL& HeadlessGL::Get() {
static HeadlessGL instance;
return instance;
}
HeadlessGL::HeadlessGL() {
m_backendName = EnvOr("MOBILEGL_BACKEND_TYPE", "<unset>");
m_usable = BringUp();
}
bool HeadlessGL::BringUp() {
// Ask a disposable copy of this process first. Only if it survived does
// the real one try - see PreflightBringUp for why nothing weaker is
// predictive against a stack that aborts instead of returning errors.
const std::string preflightProblem = PreflightBringUp();
if (!preflightProblem.empty()) {
m_skipReason = preflightProblem;
return false;
}
// Same shape as DriverBench's boot_egl(), minus the dlopen: the provider
// is this binary. A pbuffer needs no window system, but MobileGL's own
// loader still has to reach a real driver underneath - and the child
// above just proved it can.
EglBringUp brought;
std::string reason;
if (RunEglBringUp(brought, reason) != 0) {
// The pre-flight passed and the parent's identical attempt did not.
// That is a real result, not a machine without a GPU, so say so: it
// means something is different between the two attempts (a leaked
// exclusive device, an environment the child did not have).
m_skipReason = reason + " - although an identical bring-up in a forked pre-flight child succeeded";
return false;
}
m_display = brought.display;
m_surface = brought.surface;
m_context = brought.context;
m_width = kSurfaceWidth;
m_height = kSurfaceHeight;
m_renderer = std::move(brought.renderer);
return true;
}
void HeadlessGL::EndFrame() {
if (!m_usable) return;
eglSwapBuffers(static_cast<EGLDisplay>(m_display), static_cast<EGLSurface>(m_surface));
++m_frameIndex;
}
void HeadlessGL::ShutDown() {
if (!m_usable) return;
EGLDisplay display = static_cast<EGLDisplay>(m_display);
eglMakeCurrent(display, EGL_NO_SURFACE, EGL_NO_SURFACE, EGL_NO_CONTEXT);
if (m_context != nullptr) eglDestroyContext(display, static_cast<EGLContext>(m_context));
if (m_surface != nullptr) eglDestroySurface(display, static_cast<EGLSurface>(m_surface));
eglTerminate(display);
m_context = nullptr;
m_surface = nullptr;
m_display = nullptr;
m_usable = false;
m_skipReason = "the headless context has already been torn down";
}
// ---- scenario vocabulary ------------------------------------------------
namespace {
unsigned int CompileStage(GLenum stage, const char* source, std::string* outError) {
const GLuint shader = glCreateShader(stage);
glShaderSource(shader, 1, &source, nullptr);
glCompileShader(shader);
GLint compiled = 0;
glGetShaderiv(shader, GL_COMPILE_STATUS, &compiled);
if (compiled == GL_FALSE) {
char log[2048] = {};
GLsizei length = 0;
glGetShaderInfoLog(shader, sizeof(log) - 1, &length, log);
if (outError != nullptr) {
*outError = std::string(stage == GL_VERTEX_SHADER ? "vertex" : "fragment") +
" shader failed to compile: " + log;
}
glDeleteShader(shader);
return 0;
}
return shader;
}
} // namespace
unsigned int CompileProgram(const char* vertexSource, const char* fragmentSource, std::string* outError) {
const GLuint vs = CompileStage(GL_VERTEX_SHADER, vertexSource, outError);
if (vs == 0) return 0;
const GLuint fs = CompileStage(GL_FRAGMENT_SHADER, fragmentSource, outError);
if (fs == 0) {
glDeleteShader(vs);
return 0;
}
const GLuint program = glCreateProgram();
glAttachShader(program, vs);
glAttachShader(program, fs);
// Pinned rather than queried so the scenarios can set up a VAO without a
// round trip, and so a driver that reorders attributes cannot change what
// the test means.
glBindAttribLocation(program, 0, "aPos");
glBindAttribLocation(program, 1, "aColor");
glLinkProgram(program);
glDeleteShader(vs);
glDeleteShader(fs);
GLint linked = 0;
glGetProgramiv(program, GL_LINK_STATUS, &linked);
if (linked == GL_FALSE) {
char log[2048] = {};
GLsizei length = 0;
glGetProgramInfoLog(program, sizeof(log) - 1, &length, log);
if (outError != nullptr) *outError = std::string("program failed to link: ") + log;
glDeleteProgram(program);
return 0;
}
return program;
}
ColorFbo MakeColorFbo(int width, int height) {
ColorFbo target;
target.width = width;
target.height = height;
glGenTextures(1, &target.texture);
glBindTexture(GL_TEXTURE_2D, target.texture);
glTexImage2D(GL_TEXTURE_2D, 0, GL_RGBA8, width, height, 0, GL_RGBA, GL_UNSIGNED_BYTE, nullptr);
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_NEAREST);
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_NEAREST);
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_S, GL_CLAMP_TO_EDGE);
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_T, GL_CLAMP_TO_EDGE);
glBindTexture(GL_TEXTURE_2D, 0);
glGenFramebuffers(1, &target.fbo);
glBindFramebuffer(GL_FRAMEBUFFER, target.fbo);
glFramebufferTexture2D(GL_FRAMEBUFFER, GL_COLOR_ATTACHMENT0, GL_TEXTURE_2D, target.texture, 0);
const GLenum status = glCheckFramebufferStatus(GL_FRAMEBUFFER);
glBindFramebuffer(GL_FRAMEBUFFER, 0);
if (status != GL_FRAMEBUFFER_COMPLETE) {
DestroyColorFbo(target);
}
return target;
}
void DestroyColorFbo(ColorFbo& target) {
if (target.fbo != 0) glDeleteFramebuffers(1, &target.fbo);
if (target.texture != 0) glDeleteTextures(1, &target.texture);
target.fbo = 0;
target.texture = 0;
}
void BindDefaultFramebuffer() {
glBindFramebuffer(GL_FRAMEBUFFER, 0);
glViewport(0, 0, HeadlessGL::Get().Width(), HeadlessGL::Get().Height());
}
void BindFbo(const ColorFbo& target) {
glBindFramebuffer(GL_FRAMEBUFFER, target.fbo);
glViewport(0, 0, target.width, target.height);
}
void ClearTo(float r, float g, float b, float a) {
glClearColor(r, g, b, a);
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);
}
Image ReadPixels(int width, int height) {
Image image(width, height);
glPixelStorei(GL_PACK_ALIGNMENT, 1);
glReadPixels(0, 0, width, height, GL_RGBA, GL_UNSIGNED_BYTE, image.Data());
return image;
}
unsigned int FirstGLError() {
const GLenum first = glGetError();
if (first == GL_NO_ERROR) return GL_NO_ERROR;
// Drain, bounded: a broken stack must not turn an error check into a hang.
for (int i = 0; i < 64 && glGetError() != GL_NO_ERROR; ++i) {}
return first;
}
const char* GLErrorName(unsigned int error) {
switch (error) {
case GL_NO_ERROR:
return "GL_NO_ERROR";
case GL_INVALID_ENUM:
return "GL_INVALID_ENUM";
case GL_INVALID_VALUE:
return "GL_INVALID_VALUE";
case GL_INVALID_OPERATION:
return "GL_INVALID_OPERATION";
case GL_OUT_OF_MEMORY:
return "GL_OUT_OF_MEMORY";
case GL_INVALID_FRAMEBUFFER_OPERATION:
return "GL_INVALID_FRAMEBUFFER_OPERATION";
default:
return "GL_<unknown>";
}
}
} // namespace MGITest
@@ -0,0 +1,218 @@
// MobileGL - MobileGL/MG_IntegrationTest/Harness/HeadlessGL.h
// 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
//
// A headless GL context and the small vocabulary the scenarios are written in.
//
// The scenarios in this module are end-to-end: they drive MobileGL's own GL and
// EGL entry points (this binary links MobileGL_s, so gl*/egl* resolve straight
// into the implementation) and assert on glReadPixels output. Nothing here
// inspects backend state - both bugs this module pins were invisible to
// state-level assertions and visible only in pixels.
//
// Headless by construction, following MG_Benchmark/Driver/DriverBench.c: an EGL
// context on a PBUFFER surface. No window, no window manager, no human. Unlike
// DriverBench the scenarios do draw to the DEFAULT framebuffer (that is where
// the Y-flip lives) and do call eglSwapBuffers (that is the frame boundary the
// cross-frame scenarios need to be real).
//
// One process is one backend: MOBILEGL_BACKEND_TYPE is latched at
// initialization, so the CMake wiring runs this binary once per backend rather
// than trying to switch in-process.
#pragma once
#include <gtest/gtest.h>
#include <cstdint>
#include <string>
#include <vector>
namespace MGITest {
// True when MOBILEGL_ITEST_REQUIRE_GPU is set in the environment: the runner
// is asserting that this machine HAS a usable GPU, so "no GPU" stops being a
// clean skip and becomes a failure. Without it the integration-gpu label is
// unfalsifiable - a CI job that ran nothing reports exactly the same green as
// a job that ran everything.
bool RequireGpu();
struct Rgba8 {
std::uint8_t r = 0, g = 0, b = 0, a = 0;
bool operator==(const Rgba8& other) const {
return r == other.r && g == other.g && b == other.b && a == other.a;
}
bool operator!=(const Rgba8& other) const { return !(*this == other); }
};
// Prints as "rgba(255,0,0,255)" so a gtest failure names the colour it saw.
std::ostream& operator<<(std::ostream& os, const Rgba8& c);
// An RGBA8 readback. Row 0 is the BOTTOM row: that is GL's convention for
// glReadPixels and it is what "correctly oriented" means everywhere below.
class Image {
public:
Image() = default;
Image(int width, int height)
: m_width(width), m_height(height), m_pixels(static_cast<std::size_t>(width) * height * 4, 0) {}
int Width() const { return m_width; }
int Height() const { return m_height; }
bool Empty() const { return m_pixels.empty(); }
std::uint8_t* Data() { return m_pixels.data(); }
const std::uint8_t* Data() const { return m_pixels.data(); }
Rgba8 At(int x, int y) const;
// Nearest of {black, red, green, blue, white, other} - the scenarios only
// ever draw those, so this turns a pixel into something readable.
const char* ColorName(int x, int y) const;
bool operator==(const Image& other) const {
return m_width == other.m_width && m_height == other.m_height && m_pixels == other.m_pixels;
}
// Count of differing bytes, for a failure message that says how wrong.
std::size_t ByteDiffCount(const Image& other) const;
// The four quadrant centres, in the fixed order
// bottom-left, bottom-right, top-left, top-right.
//
// This replaces the old VerticalSignature(bandCount), which read three
// full-width horizontal stripes down the centre line and was therefore
// blind to an X flip, to a transpose, and to a 180 rotation composed with
// a Y flip - all of those left the stripe order alone. Four quadrant
// colours are asymmetric in BOTH axes, so each of the eight square
// symmetries produces a different string (see OrientationScenario, which
// spells all eight out).
std::string QuadrantSignature() const;
private:
int m_width = 0;
int m_height = 0;
std::vector<std::uint8_t> m_pixels;
};
// The process-wide headless context. Brought up lazily on the first Get() so
// that `--gtest_list_tests` (which CMake runs at build time to discover the
// cases) never touches a GPU.
class HeadlessGL {
public:
static HeadlessGL& Get();
// False on a machine with no usable GPU/display/ICD. SkipReason() then
// says which step failed; every fixture turns that into GTEST_SKIP().
bool Usable() const { return m_usable; }
const std::string& SkipReason() const { return m_skipReason; }
// Backend actually in use, as reported by MOBILEGL_BACKEND_TYPE.
const std::string& BackendName() const { return m_backendName; }
const std::string& RendererString() const { return m_renderer; }
int Width() const { return m_width; }
int Height() const { return m_height; }
// THE frame boundary. eglSwapBuffers is what retires a frame in the
// renderer, and the cross-frame scenarios are meaningless without it.
void EndFrame();
// Frames completed so far, for failure messages.
int FrameIndex() const { return m_frameIndex; }
// Releases the context and surface and terminates the display. Called
// once, after the last scenario: MobileGL frees its backend objects
// through eglTerminate, and letting a process simply exit on top of a
// live context leaves those objects to be torn down from a static
// destructor with no driver left underneath.
void ShutDown();
private:
HeadlessGL();
HeadlessGL(const HeadlessGL&) = delete;
HeadlessGL& operator=(const HeadlessGL&) = delete;
bool BringUp();
bool m_usable = false;
std::string m_skipReason;
std::string m_backendName;
std::string m_renderer;
int m_width = 0;
int m_height = 0;
int m_frameIndex = 0;
void* m_display = nullptr;
void* m_surface = nullptr;
void* m_context = nullptr;
};
// ---- the scenario vocabulary -------------------------------------------
// Deliberately tiny. A scenario should read like a story; anything that
// needs a comment about GL mechanics belongs here instead.
// Compiles and links vs+fs, pinning attribute 0 to "aPos" and 1 to "aColor".
// Returns 0 and fills outError on failure.
unsigned int CompileProgram(const char* vertexSource, const char* fragmentSource, std::string* outError);
struct ColorFbo {
unsigned int fbo = 0;
unsigned int texture = 0;
int width = 0;
int height = 0;
};
// A complete RGBA8 render target. Returns fbo==0 on failure.
ColorFbo MakeColorFbo(int width, int height);
void DestroyColorFbo(ColorFbo& target);
// Binds a target and sets the viewport to match. Passing fbo 0 means the
// default (presentable) framebuffer.
void BindDefaultFramebuffer();
void BindFbo(const ColorFbo& target);
void ClearTo(float r, float g, float b, float a);
// Reads back the whole currently bound READ framebuffer. width/height must
// be the target's full size - DirectVulkan's default-framebuffer readback
// only re-orients a full-extent read.
Image ReadPixels(int width, int height);
// Drains any GL error queue and returns the first error, or 0.
unsigned int FirstGLError();
const char* GLErrorName(unsigned int error);
// ---- whole-region readback predicates ----------------------------------
// The scenarios used to assert on two or three individual pixels, which is
// provably too weak: a draw in which 3 of a quad's 4 vertices carry stale
// data still paints the sampled centre the expected colour (that exact case
// is a standing negative-control test - see CrossFrameBufferScenario). The
// readback is already fully in memory, so counting every pixel in a region
// costs nothing and turns "the middle looks right" into "all of it is right".
// Everything a caller needs to say what was wrong and where.
struct RegionScan {
int total = 0; // pixels examined
int offenders = 0; // pixels whose ColorName() != expected
int firstX = -1; // first offender in bottom-to-top, left-to-right order
int firstY = -1;
Rgba8 firstColor{};
std::string firstColorName;
};
// Inclusive pixel bounds, clamped to the image. Row 0 is the bottom row.
RegionScan ScanRegion(const Image& image, int x0, int x1, int y0, int y1, const char* expectedColor);
// gtest predicate wrapper: EXPECT_TRUE(RegionIsMostly(...)) reports the
// offender count, the offender fraction and the FIRST offending pixel's
// coordinates and colour. `tolerance` is the fraction of the region allowed
// to disagree; pass 0.0 to demand every pixel (which is what the scenarios
// do - they inset their regions away from primitive edges so exactness is
// achievable).
::testing::AssertionResult RegionIsMostly(const Image& image, int x0, int x1, int y0, int y1,
const char* expectedColor, double tolerance,
const std::string& when);
} // namespace MGITest
@@ -0,0 +1,84 @@
// MobileGL - MobileGL/MG_IntegrationTest/Harness/ScenarioFixture.h
// 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
//
// The base fixture every scenario derives from. Its only jobs are to bring the
// headless context up once per process and to decide what "this machine has no
// usable GPU" means.
//
// By default it means a clean GTEST_SKIP() - never a failure, never a hang -
// because a developer box or a container without a GPU should not fail a run it
// was never able to perform. But a skip is indistinguishable from a pass in
// every CI summary, so the `integration-gpu` label on its own is unfalsifiable:
// a runner whose driver pinning silently broke reports the same green as one
// that rendered every frame. MOBILEGL_ITEST_REQUIRE_GPU is the caller saying
// "this machine HAS a GPU and I am relying on these scenarios actually running";
// with it set, an unusable harness is a FAILURE carrying the pre-flight's reason.
#pragma once
#include <gtest/gtest.h>
#include "HeadlessGL.h"
namespace MGITest {
class ScenarioTest : public ::testing::Test {
protected:
void SetUp() override {
m_ready = false;
HeadlessGL& gl = HeadlessGL::Get();
if (!gl.Usable()) {
if (RequireGpu()) {
// FAIL() is a FATAL failure but does NOT mark the test skipped,
// so a derived SetUp that guards on IsSkipped() alone would run
// straight into GL calls with no current context and SIGSEGV -
// that exact crash shipped from the first version of this guard.
// Derived fixtures must gate on Ready() (below), which is false
// on BOTH the skip path and this failure path.
FAIL() << "MOBILEGL_ITEST_REQUIRE_GPU is set, so an unusable harness is a failure, not a skip. "
<< "Backend " << gl.BackendName() << " could not be brought up: " << gl.SkipReason();
}
GTEST_SKIP() << "no usable GPU/display/ICD for backend " << gl.BackendName() << ": " << gl.SkipReason();
}
if (RequireGpu() && LooksLikeSoftwareRasterizer(gl.RendererString())) {
// "Ran on llvmpipe" must not be able to pass as "ran on the GPU":
// a misconfigured vendor pin silently lands on the software
// rasterizer, and REQUIRE_GPU exists precisely to make that loud.
FAIL() << "MOBILEGL_ITEST_REQUIRE_GPU is set but the context landed on a software rasterizer: "
<< gl.RendererString();
}
// A scenario starts from a clean slate but shares the context (and so
// the renderer's memos) with every other scenario in this process -
// which is exactly the situation both shipped bugs needed.
RecordProperty("backend", gl.BackendName());
RecordProperty("renderer", gl.RendererString());
m_ready = true;
}
// The ONLY gate a derived SetUp/TearDown may use: `if (!Ready()) return;`.
// True only when the base SetUp brought the context up and neither skipped
// nor failed. IsSkipped() alone is WRONG here (see the comment at FAIL()).
bool Ready() const { return m_ready; }
static HeadlessGL& Gl() { return HeadlessGL::Get(); }
private:
static bool LooksLikeSoftwareRasterizer(const std::string& renderer) {
static const char* kNames[] = {"llvmpipe", "lavapipe", "softpipe", "SwiftShader", "swrast"};
for (const char* name : kNames) {
if (renderer.find(name) != std::string::npos) {
return true;
}
}
return false;
}
bool m_ready = false;
};
} // namespace MGITest