// 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: desktop uses an EGL pbuffer and Android uses an // AImageReader-backed ANativeWindow that needs no Activity. 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 #include #include #include 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(); // True when MOBILEGL_ITEST_REQUIRE_HARDWARE_GPU is set: additionally asserts // that the context did NOT land on a software rasterizer. Deliberately a // SEPARATE switch from RequireGpu - a GPU-less CI runner is a supported and // intended configuration for these scenarios (they pin backend draw logic, // which llvmpipe/lavapipe execute faithfully), so CI wants the falsifiability // of REQUIRE_GPU without the hardware demand. Use this one only where a vendor // pin silently degrading to software would invalidate the measurement. bool RequireHardwareGpu(); 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(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 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. Image ReadPixels(int width, int height); // A PARTIAL glReadPixels. Row 0 of the returned image is GL row `y` of the // framebuffer, i.e. the bottom row of the requested rect - the same // convention ReadPixels uses, just with an origin. This is the shape the // conformance suite reads in (a random sub-rect of the default // framebuffer), and the shape DirectVulkan's default-FBO readback used to // hand back in Vulkan row order because its re-orientation only ran on an // exact full-extent read. Image ReadPixelsRect(int x, int y, 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