Skip to content

Run Windows games on Apple Silicon — free, open source, with an open compatibility database that tells you what actually works.

Narrow to OpenGL digest and log-header diagnostics

Tux044e740fd79f
diff --git a/README.md b/README.md
index 0b11a31..a92b36d 100644
--- a/README.md
+++ b/README.md
@@ -154,9 +154,6 @@ this repository.
macOS, chip) so stale data is visible, not silently wrong.
- **Engines**: manifest PRs bumping pinned versions, with a verification note.
-For OpenGL startup failures, slow motion or missing textures, see the
-[OpenGL troubleshooting notes](docs/opengl.md).
-
## Licensing
App + CLI + HighballKit: **GPL-3.0** ([LICENSE](LICENSE)). Recipes and database:
@@ -173,4 +170,4 @@ free Mac Wine supply chain) · [CodeWeavers](https://www.codeweavers.com) (the C
the Wine 11 engine is built from) · [3Shain's DXMT](https://github.com/3Shain/dxmt) ·
[Sikarugir](https://github.com/Sikarugir-App/Sikarugir) · Apple's Game Porting Toolkit ·
[Whisky](https://github.com/Whisky-App/Whisky), whose honesty about its own limits shaped
-this design.
+this design.
\ No newline at end of file
diff --git a/Sources/HighballApp/AppState.swift b/Sources/HighballApp/AppState.swift
index bad7f45..3aa45cd 100644
--- a/Sources/HighballApp/AppState.swift
+++ b/Sources/HighballApp/AppState.swift
@@ -129,8 +129,6 @@ final class AppState {
/// The library item this launch belongs to, when it is a game: accepting then changes the
/// mode for that game alone, never the whole environment.
var itemID: String? = nil
- /// A detected OpenGL failure needs its own advice, not a Direct3D mode trial.
- var openGLRecovery: Recovery? = nil
}
/// A game that ran, badly by the player's account, with another mode to try next time (the
@@ -202,12 +200,6 @@ final class AppState {
return
}
let current = record.renderer.flatMap(Renderer.init(rawValue:)) ?? rendererOverride(for: item) ?? bottle.settings.renderer
- if current != .wined3d, let log = lastLaunchLog(for: item), let recovery = Recovery.openGL(log: log) {
- fail(HighballError.failed(recovery.headline), bottle: bottle)
- errorRecovery = recovery
- errorDetailsText = recovery.headline + "\n" + recovery.meaning + "\n" + log.path
- return
- }
let next = Renderer.suggestion(after: current, d3dmetalAvailable: engine.rendererDir("d3dmetal") != nil,
vkd3dAvailable: engine.rendererDir("vkd3d") != nil)
rendererTrial = RendererTrial(itemID: item.id, title: item.title, current: current, next: next)
@@ -2587,7 +2579,7 @@ final class AppState {
self.crashSuggestion = CrashSuggestion(program: pin.name, bottleName: bottle.name,
renderer: Renderer.suggestion(after: current, d3dmetalAvailable: engine.rendererDir("d3dmetal") != nil, vkd3dAvailable: engine.rendererDir("vkd3d") != nil),
logPath: result.log.path, current: current, seconds: Int(result.duration),
- alternateEngine: self.alternateEngine(for: bottle), openGLRecovery: Recovery.openGL(log: result.log))
+ alternateEngine: self.alternateEngine(for: bottle))
}
guard handedOff else { return }
if steamUI {
@@ -2756,8 +2748,7 @@ final class AppState {
self.crashSuggestion = CrashSuggestion(program: game.name, bottleName: bottle.name,
renderer: Renderer.suggestion(after: current, d3dmetalAvailable: engine.rendererDir("d3dmetal") != nil, vkd3dAvailable: engine.rendererDir("vkd3d") != nil),
logPath: result.log.path, current: current, seconds: Int(result.duration),
- alternateEngine: self.alternateEngine(for: bottle), itemID: "steam:\(game.appid)",
- openGLRecovery: Recovery.openGL(log: result.log))
+ alternateEngine: self.alternateEngine(for: bottle), itemID: "steam:\(game.appid)")
}
guard handedOff else { return }
beginSession(GameSession(title: game.name, bottleName: bottle.name, appid: game.appid, markers: markers,
@@ -3048,7 +3039,7 @@ final class AppState {
self.crashSuggestion = CrashSuggestion(program: game.app_title, bottleName: bottle.name,
renderer: Renderer.suggestion(after: current, d3dmetalAvailable: engine.rendererDir("d3dmetal") != nil, vkd3dAvailable: engine.rendererDir("vkd3d") != nil),
logPath: result.log.path, current: current, seconds: Int(result.duration),
- alternateEngine: self.alternateEngine(for: bottle), openGLRecovery: Recovery.openGL(log: result.log))
+ alternateEngine: self.alternateEngine(for: bottle))
}
guard handedOff else { return }
beginSession(GameSession(title: game.app_title, bottleName: bottle.name, appid: nil, markers: markers,
diff --git a/Sources/HighballApp/HighballApp.swift b/Sources/HighballApp/HighballApp.swift
index bce7ba9..18cf094 100644
--- a/Sources/HighballApp/HighballApp.swift
+++ b/Sources/HighballApp/HighballApp.swift
@@ -582,16 +582,13 @@ private extension View {
@MainActor func crashAlert(_ state: AppState, title: String) -> some View {
self.alert(title, isPresented: Binding(get: { state.crashSuggestion != nil }, set: { if !$0 { state.crashSuggestion = nil } }),
presenting: state.crashSuggestion) { s in
- // WineD3D itself may be the OpenGL caller, so another Direct3D mode can help it.
- if s.openGLRecovery == nil || s.current == .wined3d {
- Button(s.itemID == nil ? "Use \(s.renderer.rawValue.uppercased())" : String(format: L("Use %@ for this game"), s.renderer.rawValue.uppercased())) {
- if let itemID = s.itemID {
- state.setRendererOverride(s.renderer, for: itemID) // this game only; the environment keeps its mode
- } else if var bottle = state.bottles.first(where: { $0.name == s.bottleName }) {
- bottle.settings.renderer = s.renderer
- bottle.settings.rendererExplicit = true // the user picked it; recipes must not clobber it (#29)
- state.update(bottle)
- }
+ Button(s.itemID == nil ? "Use \(s.renderer.rawValue.uppercased())" : String(format: L("Use %@ for this game"), s.renderer.rawValue.uppercased())) {
+ if let itemID = s.itemID {
+ state.setRendererOverride(s.renderer, for: itemID) // this game only; the environment keeps its mode
+ } else if var bottle = state.bottles.first(where: { $0.name == s.bottleName }) {
+ bottle.settings.renderer = s.renderer
+ bottle.settings.rendererExplicit = true // the user picked it; recipes must not clobber it (#29)
+ state.update(bottle)
}
}
if let alt = s.alternateEngine {
@@ -611,11 +608,7 @@ private extension View {
s.renderer.rawValue.uppercased(), alt.id)
} ?? String(format: L("That usually means the graphics mode doesn't suit it on this Mac. Highball can switch this bottle to %@."),
s.renderer.rawValue.uppercased())
- if let recovery = s.openGLRecovery {
- Text(recovery.headline + " " + recovery.meaning)
- } else {
- Text(seen + " " + next)
- }
+ Text(seen + " " + next)
}
}
}
diff --git a/Sources/HighballKit/OpenGLRecovery.swift b/Sources/HighballKit/OpenGLRecovery.swift
deleted file mode 100644
index 6644d72..0000000
--- a/Sources/HighballKit/OpenGLRecovery.swift
+++ /dev/null
@@ -1,30 +0,0 @@
-import Foundation
-
-extension Recovery {
- /// Only the driver's or engine's own failure lines justify OpenGL advice. An opengl32
- /// import, a Vulkan extension list, or a null-pointer crash alone does not name the cause.
- public static func openGL(output: String) -> Recovery? {
- let lines = output.split(separator: "\n").map { $0.lowercased() }
- if lines.contains(where: { $0.contains("opengl error") && $0.contains("cctexture2d.cpp") && $0.contains("initwithmipmaps") }) {
- return Recovery(headline: "The game could not initialize some textures.",
- meaning: "Its OpenGL texture setup reported an error, which can leave parts of the scene blank. The log does not establish whether the asset or the OpenGL driver rejected it. Try the original assets if they were modified, or an OpenGL driver verified for this program. The Direct3D graphics modes do not select a game's OpenGL driver.")
- }
- if lines.contains(where: {
- ($0.contains("gl.renderer:") || $0.contains("opengl renderer")) &&
- ($0.contains("llvmpipe") || $0.contains("softpipe") || $0.contains("software rasterizer"))
- }) {
- return Recovery(headline: "The game's OpenGL renderer is using the CPU.",
- meaning: "Software rendering can cause stutter or slow motion. A compatible GPU OpenGL driver, such as Mesa Zink through Vulkan, may help. It must work with this engine's MoltenVK build. Changing the Direct3D graphics mode alone will not enable it.")
- }
- if lines.contains(where: { $0.contains("os x only supports forward-compatible 3.2+ contexts") }) {
- return Recovery(headline: "The game's OpenGL context was rejected.",
- meaning: "Highball enables forward-compatible OpenGL contexts by default. Remove any CX_FWD_COMPAT_GL_CTX=0 override from the environment and this program, stop the environment, then launch again. If it still fails, include the launch log in a report.")
- }
- return nil
- }
-
- /// Use the same bounded read as bug reports, even when a session has produced a huge log.
- public static func openGL(log: URL) -> Recovery? {
- BugReport.boundedText(of: log).flatMap { openGL(output: $0) }
- }
-}
diff --git a/Tests/HighballKitTests/OpenGLDiagnosticsTests.swift b/Tests/HighballKitTests/OpenGLDiagnosticsTests.swift
new file mode 100644
index 0000000..10c4528
--- /dev/null
+++ b/Tests/HighballKitTests/OpenGLDiagnosticsTests.swift
@@ -0,0 +1,22 @@
+import XCTest
+@testable import HighballKit
+
+final class OpenGLDiagnosticsTests: XCTestCase {
+ private let textureError = #"OpenGL error 0x0501 in ..\renderer\CCTexture2D.cpp cocos2d::Texture2D::initWithMipmaps 669"#
+
+ func testReportKeepsOpenGLIdentityAndErrorsBeforeTheTail() {
+ let identities = ["gl.version: 4.6.0 Compatibility Profile", "gl.vendor: Mesa", "gl.renderer: zink Vulkan Apple M3"]
+ let text = (identities + [textureError, textureError] + (0..<100).map { "chatter \($0)" }).joined(separator: "\n")
+ let digest = BugReport.digest(text)
+ for identity in identities { XCTAssertTrue(digest.contains(identity)) }
+ XCTAssertTrue(digest.contains(textureError + " (x2)"))
+ XCTAssertEqual(digest.components(separatedBy: "initWithMipmaps").count - 1, 1)
+ }
+
+ func testHeaderKeepsOnlyNamedOpenGLSwitches() {
+ let env = ["GALLIUM_DRIVER": "zink", "LIBGL_ALWAYS_SOFTWARE": "0", "MESA_LOADER_DRIVER_OVERRIDE": "zink",
+ "MESA_SHADER_CACHE_DIR": "/private/path", "GALLIUM_TOKEN": "secret", "SECRET": "secret"]
+ XCTAssertEqual(WineRunner.headerSwitchLines(env),
+ "# GALLIUM_DRIVER=zink\n# LIBGL_ALWAYS_SOFTWARE=0\n# MESA_LOADER_DRIVER_OVERRIDE=zink\n")
+ }
+}
diff --git a/Tests/HighballKitTests/OpenGLRecoveryTests.swift b/Tests/HighballKitTests/OpenGLRecoveryTests.swift
deleted file mode 100644
index 3f9b04d..0000000
--- a/Tests/HighballKitTests/OpenGLRecoveryTests.swift
+++ /dev/null
@@ -1,59 +0,0 @@
-import XCTest
-@testable import HighballKit
-
-final class OpenGLRecoveryTests: XCTestCase {
- private let textureError = #"OpenGL error 0x0501 in ..\renderer\CCTexture2D.cpp cocos2d::Texture2D::initWithMipmaps 669"#
-
- func testTextureFailureTakesPrecedenceOverSoftwareRendering() throws {
- let recovery = try XCTUnwrap(Recovery.openGL(output: "gl.renderer: llvmpipe (LLVM 23.1.2)\n" + textureError))
- XCTAssertEqual(recovery.headline, "The game could not initialize some textures.")
- XCTAssertEqual(recovery.action, .none)
- XCTAssertNil(recovery.actionTitle, "no unverified automatic driver change")
- XCTAssertTrue(recovery.meaning.contains("does not establish"), "a GL error alone cannot distinguish assets from driver bugs")
- }
-
- func testSoftwareRendererNeedsAnActualRendererLine() {
- for renderer in ["llvmpipe (LLVM 23.1.2, 128 bits)", "softpipe", "Software Rasterizer"] {
- XCTAssertEqual(Recovery.openGL(output: "gl.renderer: \(renderer)")?.headline,
- "The game's OpenGL renderer is using the CPU.")
- }
- XCTAssertNotNil(Recovery.openGL(output: "OpenGL renderer string: llvmpipe"))
- XCTAssertNil(Recovery.openGL(output: "# GALLIUM_DRIVER=llvmpipe\nVK_EXT_texture_compression_astc_hdr"),
- "requested settings and supported extensions do not prove which renderer ran")
- XCTAssertNil(Recovery.openGL(output: "gl.renderer: zink Vulkan 1.2 (Apple M3)"))
- XCTAssertNil(Recovery.openGL(output: "gl.renderer: M3 (WineMetalGL)"))
- }
-
- func testKnownContextRejectionButNoGuessFromANullPointer() {
- XCTAssertEqual(Recovery.openGL(output: "warn:wgl:macdrv_wglCreateContextAttribsARB OS X only supports forward-compatible 3.2+ contexts")?.headline,
- "The game's OpenGL context was rejected.")
- XCTAssertNil(Recovery.openGL(output: "Ready for OpenGL 2.0\nwine: Unhandled page fault on read access to 00000000"))
- XCTAssertNil(Recovery.openGL(output: "OpenGL error 0x0501 in some unrelated operation"))
- XCTAssertNil(Recovery.openGL(output: ""))
- }
-
- func testRecoveryReadsABoundedLogAndHandlesMissingFiles() throws {
- let file = FileManager.default.temporaryDirectory.appending(path: "hb-gl-\(UUID().uuidString).log")
- defer { try? FileManager.default.removeItem(at: file) }
- XCTAssertNil(Recovery.openGL(log: file))
- let noise = String(repeating: "chatter\n", count: 100_000)
- try (noise + textureError).write(to: file, atomically: true, encoding: .utf8)
- XCTAssertEqual(Recovery.openGL(log: file)?.headline, "The game could not initialize some textures.")
- }
-
- func testReportKeepsOpenGLIdentityAndTextureErrorsBeforeTheTail() {
- let identities = ["gl.version: 4.6.0 Compatibility Profile", "gl.vendor: Mesa", "gl.renderer: zink Vulkan Apple M3"]
- let text = (identities + [textureError, textureError] + (0..<100).map { "chatter \($0)" }).joined(separator: "\n")
- let digest = BugReport.digest(text)
- for identity in identities { XCTAssertTrue(digest.contains(identity)) }
- XCTAssertTrue(digest.contains(textureError + " (x2)"))
- XCTAssertEqual(digest.components(separatedBy: "initWithMipmaps").count - 1, 1)
- }
-
- func testHeaderKeepsOnlyNamedOpenGLSwitches() {
- let env = ["GALLIUM_DRIVER": "zink", "LIBGL_ALWAYS_SOFTWARE": "0", "MESA_LOADER_DRIVER_OVERRIDE": "zink",
- "MESA_SHADER_CACHE_DIR": "/private/path", "GALLIUM_TOKEN": "secret", "SECRET": "secret"]
- XCTAssertEqual(WineRunner.headerSwitchLines(env),
- "# GALLIUM_DRIVER=zink\n# LIBGL_ALWAYS_SOFTWARE=0\n# MESA_LOADER_DRIVER_OVERRIDE=zink\n")
- }
-}
diff --git a/docs/opengl.md b/docs/opengl.md
deleted file mode 100644
index 9f7be60..0000000
--- a/docs/opengl.md
+++ /dev/null
@@ -1,89 +0,0 @@
-# OpenGL startup, slow motion and missing textures
-
-DXMT, DXVK, D3DMetal and vkd3d select Direct3D implementations. A program that
-draws with OpenGL directly still uses its OpenGL driver when those settings change.
-WineD3D also uses OpenGL on some engines, so an OpenGL error by itself does not
-prove that a program uses OpenGL directly.
-
-## Startup failures
-
-Highball sets `CX_FWD_COMPAT_GL_CTX=1` for engines that support the CrossOver
-switch. It lets programs request a forward-compatible OpenGL 3.2+ core context
-when they omit that flag. If the log says `OS X only supports forward-compatible
-3.2+ contexts`, remove any environment or per-program override setting the switch
-to `0`, stop the environment and restart it.
-
-That switch cannot supply newer functions in a legacy compatibility context.
-In a local test of a 32-bit Cocos2d program on an Apple M3, Apple's OpenGL 2.1
-compatibility context left a vertex-array-object function pointer null and the
-program crashed during initialization. Patching the program to skip that call
-only exposed another failure. Supplying a different OpenGL implementation got
-past initialization without modifying the engine DLL.
-
-## Mesa workaround for an isolated test environment
-
-This is a manual compatibility experiment, not a shipped Highball graphics mode.
-It was exercised with engine `x64-sikarugir10.0_6-r28` on an Apple M3. Other engine,
-Mesa and MoltenVK combinations need their own verification.
-
-1. Close programs in the source environment, then make a copy with
- `highball bottle duplicate "SOURCE" "OpenGL test"`. This command stops the source
- environment before copying it. Use the copy for the steps below.
-2. Obtain the appropriate Windows build from
- [Mesa for Windows releases](https://github.com/pal1000/mesa-dist-win/releases/tag/24.3.4).
- The tested archive was `mesa3d-24.3.4-release-msvc.7z`, SHA-256
- `7ebc711ad1896ac88ab21e142f1017f8ff035f0f342bdb72fbb5e2eb881ba363`.
- Check the archive hash before extracting it.
-3. For the tested **32-bit** program, place the archive's `x86/opengl32.dll`,
- `x86/libglapi.dll` and `x86/libgallium_wgl.dll` in the test prefix's
- `drive_c/windows/syswow64`, keeping copies of any replaced files. In a WoW64
- prefix, `syswow64` holds 32-bit DLLs and `system32` holds 64-bit DLLs. Do not
- mix architectures or DLLs from different Mesa releases.
-4. In the test program's environment variables, set `WINEDLLOVERRIDES=opengl32=n`
- and `GALLIUM_DRIVER=zink`. The tested environment also had
- `MVK_SHADOW_IMPORT=1`, a switch in that engine's patched MoltenVK. Preserve any
- other DLL overrides the program needs.
- Merely copying the DLLs is insufficient if Wine still loads its builtin
- `opengl32`. A program started by an existing launcher inherits that launcher's
- environment, so stop it and relaunch it with the same settings.
-5. Inspect the program's OpenGL renderer information. A renderer naming Zink and
- the Apple GPU confirms the GPU path. A requested `GALLIUM_DRIVER=zink` alone
- does not prove it ran. Test the affected scenes, not just the title screen.
-
-Zink translates OpenGL through Vulkan and the engine's MoltenVK. A newer Mesa
-build tested locally required a Vulkan capability unavailable in that MoltenVK
-build and did not start. Mesa 24.3.4 did start through Zink and restored normal
-movement speed in the tested program, but emitted unsupported-feature warnings
-and some scenes still needed investigation. This is why this configuration is
-not enabled globally.
-
-The software renderer, `llvmpipe`, also got past initialization, but CPU use was
-roughly 340% and the program ran in slow motion. Zink reduced it to roughly 75%
-in that local comparison. These are observations from one program, not a
-benchmark or a compatibility promise. Software rendering is useful to diagnose
-a driver problem, but is a poor default for playing.
-
-To roll back, stop the test environment and return to the source environment.
-To restore the test prefix itself, restore its backed-up DLLs and remove the
-OpenGL DLL override and Mesa environment settings. Remove any corresponding
-registry override if one was added separately.
-
-## White backgrounds or missing textures
-
-Errors such as `OpenGL error 0x0501` from
-`cocos2d::Texture2D::initWithMipmaps` mean texture initialization reported an
-invalid value. They do not establish whether the image dimensions, format,
-assets or driver caused it. Check unchanged original assets and capture the
-actual OpenGL renderer, version and texture-size limit before changing drivers.
-
-[WineMetalGL](https://github.com/metalsharp/WineMetalGL) is another OpenGL
-implementation. A local Wine 11 / WineMetalGL 3.4.0 test started successfully and
-reduced CPU use, but later produced these texture errors and white backgrounds.
-A successful launch is not sufficient evidence to recommend it as a replacement
-for every program or to call texture rendering fixed.
-
-Highball's recovery advice recognizes explicit texture initialization failures,
-software-renderer identity lines and the known core-context rejection. A null
-pointer crash or an `opengl32` import alone is insufficient for that advice.
-Reports retain OpenGL renderer identity and texture errors, along with the
-selected Mesa driver switches, without including the full environment.