mirror of
https://github.com/MobileGL-Dev/MobileGL
synced 2026-11-07 01:53:24 +09:00
swung0x48
583e12de76
CONTRACT-P7 §3.2's `default-color-blit-shape@P7`, retired in three pieces, because one
Fatal was covering three unrelated situations.
The shader pass it guarded is there for ROTATION and nothing else: it can only SAMPLE
its source - sampler2D, a float result, one of two 2D view types - so an RGBA8UI
attachment, a 3D slice or an array layer made it return false. The refusal then fired
EVEN ON A SURFACE WITH NO ROTATION, where the ordinary vkCmdBlitImage arm twenty lines
below would have done the blit and does handle those shapes.
- identity: fall through to that arm;
- a non-identity rotation with a source the pass cannot sample: move the region into an
owned 2D single-sample image of a sampled-float format in the SAME size-compatibility
class and shader-blit that;
- outside the four rotations (a mirror, or a mirror-rotation): decline by name, saying
which transform. Neither arm can express a reflection and this package has no device
that reports one to check a result against.
Reinterpretation is the point for the integer case and GL agrees: glBlitFramebuffer
between an integer and a normalized format is INVALID_OPERATION (4.6 core 18.3.1), so
there is no defined result to be wrong about - only a shape that used to end the session
and now produces the source's bits. For a float source of the wrong view type the copy
is a plain slice extraction and the result is exactly right.
THE RETIREMENT UNCOVERED A REAL BUG, which is the part worth reading. The ordinary blit
arm addressed a 3D source as `{aspect, level, source.layer, 1}` with z 0..1. A 3D image's
slice rides Z; its only subresource is layer 0 - which is how the copy endpoint's
CopyImageSliceMapping and the multisample resolve arm above already address one. So a
blit from slice 1 of a 3D texture read slice 0, out of a layer the image does not have.
It was invisible because that shape hit the Fatal first and never reached the arm: the
new scenario's first run had the scratch arm correct and the fall-through arm wrong in
all four quadrants, which is how it fell out. Both arms agree now.
The scenario's source is slice 1 of a 3D texture - ordinary GL, and exactly the shape the
shader pass cannot sample - with slice 0 filled in a colour that appears in no quadrant,
so a scratch copy that forgot the z origin would still be reading real texels and had to
be made distinguishable. It is registered twice on each arm: plain, taking the identity
fall-through, and under MGITEST_MAGMA_FORCE_DEFAULT_BLIT_SCRATCH, taking the rotated
arm's scratch path on an identity surface, where it must produce THE SAME PIXELS. That
equality is the assertion, and it is the only way the scratch arm is reachable from a
host lane at all: every surface this lane can create reports
VK_SURFACE_TRANSFORM_IDENTITY, as does the Redmi pbuffer this cluster's evidence comes
from. The knob does not fake a rotation - nothing downstream is told the surface turned.
Red once (executed, reverted): with MagmaWireFatal("default-color-blit-shape@P7")
restored, both entries die by that name; without it, 2/2 green.
Gates: integration-magma-split 81 (+2), -spawn 60 (+2), -tcp 62 (+2), 0 red;
ctest -L unit 2410; informational integration-magma-full-split 516, 0 red, 59 skip;
fatal_census green; link_ratchet --assert-monotone unchanged at 186, p7-magma 101;
G1 pull .text 0xa52203, defined-symbol name list identical (30570).
Owed to a device window: the scratch arm's geometry under a REAL ROTATE_90/180/270. The
knob proves it produces the fall-through's pixels on an identity surface, which exercises
every line of it except the rotation constant the vertex shader applies.
WireColorBlit.inc and VulkanRenderer.h are edited outside this package's named file list.
Both belong to this cluster (the colour blit's implementation, and four private
declarations beside the existing blit ones); flagged for the integrator.
MobileGL
A desktop OpenGL implementation
MobileGL is a free and open-source project that implements a desktop OpenGL API. The goal is to provide a complete desktop OpenGL implementation with a state management layer and multi-backend support.
Note
Status: In development. Parts of the codebase are incomplete. Current short-term target: OpenGL 4.2 (Core Profile).
Project positioning
MobileGL is an implementation of a desktop OpenGL library. It aims to provide:
- Full OpenGL state management.
- A front-end that exposes OpenGL functions.
- Multiple independent backend implementations, where each backend targets a specific graphics API and remains fully isolated from others.
This project is intended as an implementation/translation layer.
Key components
The repository is organized into following top-level modules:
- MG_State — state tracking and management logic for Graphics APIs.
- MG_Impl — front-end implementations of Graphics APIs that interact with
MG_StateandMG_Backend. - MG_Backend — per-backend translation layer that maps front-end Graphics APIs' semantics and state into concrete backend API calls (e.g. OpenGL ES, Vulkan).
- MG_Util and other utility modules.
Third-party components
MobileGL reuses several open-source projects:
- SPIRV-Cross by KhronosGroup - Apache License 2.0: github
- glslang by KhronosGroup - Various Licenses: github
- DiligentCore by Diligent Graphics - Apache License 2.0: github
- flat_hash_map by Malte Skarupke - Boost Software License 1.0: github
Refer to each component's repository for exact license texts. Any bundled third-party code in this repository is included under the upstream project's license.
Compatibility & target
- Short-term target:
OpenGL 4.2 (Core Profile). - Current development focus:
- Performance improvement
MG_StateandMG_ImplforOpenGL 4.2 (Core Profile)Direct (Vulkan)backendDirect (OpenGL ES)backend
Build Instructions
We currently provide no releases and no precompiled binaries.
If you want to try the project right now, you’ll need to build it yourself:
-
Clone the repository:
git clone https://github.com/MobileGL-Dev/MobileGL.git -
Initialize and update all submodules recursively:
git submodule update --init --recursive -
Follow glslang’s own documentation for its required initiation.
-
Configure and build the project with CMake:
cmake -B build cmake --build buildor do it in a modern way:
cmake -S . -B build -G Ninja -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ cmake --build buildAlternatively, you can use platform-specific build commands as needed.
Build For macOS
On macOS, MobileGL can be built as a dylib that exposes the normal OpenGL/CGL/NSOpenGL entry points and routes them to the DirectVulkan backend. This is useful for running applications such as Minecraft through their stock GLFW/LWJGL OpenGL path while MobileGL is injected before context creation.
Prerequisites:
- macOS with Clang and Ninja.
- Vulkan loader and MoltenVK installed. With Homebrew, the MoltenVK ICD is commonly located at
/opt/homebrew/etc/vulkan/icd.d/MoltenVK_icd.json.
Configure and build:
cmake -S . -B build-macos-magma \
-G Ninja \
-DCMAKE_BUILD_TYPE=Release \
-DMOBILEGL_BACKEND_TYPE=DirectVulkan \
-DMOBILEGL_BUILD_TEST=OFF \
-DMOBILEGL_BUILD_BENCHMARK=OFF
cmake --build build-macos-magma --target MobileGL -j8
The dylib will be generated at:
build-macos-magma/libMobileGL.dylib
To run Minecraft by MobileGL from a launcher like PrismLauncher, keep the stock LWJGL/GLFW natives and add a wrapper command to the instance settings:
env DYLD_INSERT_LIBRARIES=/absolute/path/to/MobileGL/build-macos-magma/libMobileGL.dylib MOBILEGL_BACKEND_TYPE=DirectVulkan VK_ICD_FILENAMES=/opt/homebrew/etc/vulkan/icd.d/MoltenVK_icd.json
Also make sure the JVM arguments include:
-XstartOnFirstThread
DYLD_INSERT_LIBRARIES must be active before GLFW creates its OpenGL context. After startup, the Minecraft F3 screen should report MobileGL and the Direct (Vulkan) backend if the injection worked.
Build Options
| Option | Description | Default |
|---|---|---|
MOBILEGL_BUILD_TEST |
Build MobileGL tests (requires Clang) | ON |
MOBILEGL_BUILD_BENCHMARK |
Build MobileGL benchmarks (requires Clang) | ON |
MOBILEGL_FORCE_RELEASE_OPT |
Enable O3 and LTO in Debug build | ON |
MOBILEGL_ENABLE_TRACY |
Enable Tracy profiler for performance analysis | OFF |
Notes:
- The project requires C++23.
MG_TestandMG_Benchmarkcan only be built with Clang, not GCC. To enforce Clang, add-DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++to your command.- On Android, tests and benchmarks are always disabled.
Environment Variables
MobileGL supports runtime configuration via environment variables.
Supported Keys
| Variable | Description | Allowed Values | Default |
|---|---|---|---|
MOBILEGL_BACKEND_TYPE |
Select active backend implementation at startup. | DirectGLES, DirectVulkan |
DirectGLES |
MOBILEGL_DISABLE_TIMERQUERY |
Disable GPU timer-query exposure and use. | 0, 1 |
0 |
MOBILEGL_ESPRYT_USE_ANGLE |
Load ANGLE EGL/GLES libraries. | 0, 1 |
0 |
MOBILEGL_MAGMA_DISABLE_SUBGROUP |
Disable Vulkan shader subgroup support. | 0, 1 |
0 |
MOBILEGL_ADVERTISE_FP64 |
Advertise GL_ARB_gpu_shader_fp64. GLSL double/dvec/dmat compile and run either way - they are narrowed to 32 bits - so this only changes whether an application is told it has 64-bit precision, which it does not. |
0, 1 |
0 |
MOBILEGL_MAGMA_R11G11B10F_FALLBACK |
Use Magma's R11G11B10F format fallback. | 0, 1 |
0 |
MOBILEGL_MAGMA_FRAMESINFLIGHT |
Set Magma frames in flight. | Integer 1–64 |
3 |
MOBILEGL_ESPRYT_AVOID_SAMPLER_MIPMAP_MIN_FILTER |
Avoid sampler mipmap minification filters. | 0, 1 |
0 |
MOBILEGL_COHERENT_AS_FLUSH |
Treat persistent GL_MAP_FLUSH_EXPLICIT_BIT maps as coherent (app-compat for engines like Flywheel that never flush them). |
0, 1 |
0 |
MOBILEGL_ESPRYT_FORCE_DS_READBACK_EMULATION |
Always emulate depth/stencil glReadPixels/glGetTexImage by shader sampling on Espryt, instead of using the driver's own depth/stencil readback where it has one. |
0, 1 |
0 |
VK_ICD_FILENAMES |
Select the Vulkan ICD used by the Vulkan loader. | Path to an ICD JSON file | Loader default |
License
This project is distributed under GNU LGPL v3.0. See the LICENSE file in the repository for detailed information.