Skip to content

Build Apple frameworks for iOS, tvOS, watchOS and visionOS, and support EAGL contexts - #1075

Open
Coastrnaut wants to merge 5 commits into
projectM-visualizer:masterfrom
Coastrnaut:ios
Open

Coastrnaut wants to merge 5 commits into
projectM-visualizer:masterfrom
Coastrnaut:ios

Conversation

@Coastrnaut

Copy link
Copy Markdown

This makes projectM usable as a framework on iOS, iPadOS, tvOS, watchOS and visionOS, and makes projectm_create_with_opengl_load_proc() work with an EAGL context.

Framework bundles on the iOS family

ENABLE_MACOS_FRAMEWORK now applies to every Apple platform. macOS keeps the versioned bundle (Versions/A plus symlinks), unchanged. On the iOS family the bundle is shallow, as those platforms require:

  • binary, Info.plist and Headers/ at the bundle root, with the C headers flat in Headers/, so clients #include <projectM-4/projectM.h> through the framework search path;
  • CFBundleSupportedPlatforms (iPhoneOS, iPhoneSimulator, AppleTVOS, …) and MinimumOSVersion in Info.plist.

On all Apple platforms the library's install name now points into the bundle (@rpath/projectM-4.framework/projectM-4, or …/Versions/A/projectM-4 on macOS) instead of the plain dylib name, which doesn't exist inside the framework.

For the flat Headers/ directory, the public C headers of both libraries now include their sibling headers by file name ("types.h", "playlist_types.h") instead of "projectM-4/…". This resolves the same way in the installed include/projectM-4 tree and in the macOS framework. The playlist's "projectM-4/types.h" include stays, and resolves through projectM-4.framework. The generated header directory is added to the build include path for the export and version headers.

GLResolver with an application-managed context

  • EAGL context. When Initialize() can't probe a current context but the app supplied a resolver, it already assumes an app-managed context (GLResolver: fall back to app-managed EGL/GLES when a user resolver is set #1010). VerifyBeforeUse() then probed again, found no EGL context and refused with Context for detected backend is not available (backend=EGL). With EAGL on iOS that always happens, since none of the probed backends can see it. The resolver state now records that the context is app-managed, and VerifyBeforeUse() trusts it in that case.
  • User resolver is authoritative on Apple embedded platforms. There is no system EGL, desktop GL or CGL library there; GL ES comes from the app (Apple's OpenGL ES framework, or ANGLE through eglGetProcAddress). With a user resolver, the resolver no longer tries to dlopen eleven EGL/GLES library names that don't exist there, and returns the user resolver's result without falling back to dlsym(RTLD_DEFAULT) and library lookups. Other platforms, and Apple embedded platforms without a user resolver, are unchanged.

CI

New build-framework-embedded job in the macOS workflow, for iOS, the iOS simulator and tvOS. It builds and installs the frameworks with GLES, then:

  • checks the shallow layout, Info.plist keys and install names;
  • checks that the playlist framework links to projectM-4.framework;
  • compiles and links a small C client against both frameworks with -F/-framework.

Testing

  • Windows (MSVC): full build with tests and the playlist library enabled. All unit tests pass, and TestPlaylistAPIHeaders compiles the changed playlist headers.
  • I loaded all 14,536 presets from cream-of-the-crop, en-d, milkdrop-original and projectm-classic one after another (Windows, RTX A6000), rendered 30 frames each with fixed audio and frame times, and recorded shader compile/link results, failed loads and frame hashes. The results are identical to master. Both builds had their random seeds fixed for the comparison (a local patch only).
  • Apple platforms: I don't have a Mac here, so the macOS framework job and the new iOS/tvOS job are verified only by CI on this PR.

ENABLE_MACOS_FRAMEWORK now applies to every Apple platform. On macOS the
bundle stays versioned; on the iOS family it is shallow (binary,
Info.plist and Headers at the root, C headers flat so clients include
<projectM-4/projectM.h>), with CFBundleSupportedPlatforms and
MinimumOSVersion in Info.plist.

The library's install name now points into the bundle
(@rpath/projectM-4.framework/projectM-4, or .../Versions/A/projectM-4 on
macOS) instead of the plain dylib name.

The public C headers include each other by file name ("types.h")
rather than "projectM-4/types.h", so they resolve in a flat framework
Headers directory as well as in the installed include/projectM-4 tree.
The generated header directory is added to the build include path for
projectM_export.h and version.h.
… is supplied

When Initialize() cannot probe a current context but the application
supplied its own resolver, it already proceeds on the assumption that
the application manages the context. VerifyBeforeUse() then probed
again, found no EGL context and refused, so GladLoader failed with
"Context for detected backend is not available (backend=EGL)".

That is always the case with EAGL on iOS, which none of the probed
backends can see, so projectm_create_with_opengl_load_proc() could
never succeed there. The resolver state now records that the context
is application-managed, and VerifyBeforeUse() trusts it in that case.
iOS, iPadOS, tvOS, watchOS and visionOS have no system EGL, desktop GL
or CGL library: GL ES comes from the application (Apple's OpenGL ES
framework, or an ANGLE build through eglGetProcAddress). With a user
resolver supplied, Initialize() still tried to dlopen eleven EGL/GLES
library names that do not exist there, and ResolveProcAddress() fell
back to dlsym(RTLD_DEFAULT) and library lookups whenever the resolver
returned null.

On these platforms, when the application supplies a resolver, the
resolver now opens no native libraries and returns the user resolver's
result without fallback. Other platforms, and Apple embedded platforms
without a user resolver, are unchanged.
GLResolver.cpp included <TargetConditionals.h> inside the _WIN32 block,
so TARGET_OS_IPHONE was never defined on Apple platforms unless another
header happened to pull it in, and IsAppleEmbeddedPlatform() returned
false on iOS.

The playlist headers included each other as "projectM-4/playlist_*.h".
In the shallow iOS-family framework the headers sit flat in Headers/,
so these includes did not resolve. They now use the file name, like the
core headers; "projectM-4/types.h" still resolves through the
projectM-4 framework.

Adds a CI job that builds the frameworks for iOS, the iOS simulator and
tvOS, checks the bundle layout, Info.plist and install names, and
compiles and links a client against them.
Custom shapes (fill and outline), the darken-center fan and looped
waveforms used GL_TRIANGLE_FAN and GL_LINE_LOOP. GLES implementations
without native fans or loops emulate them per draw. ANGLE's Metal
backend (Metal has neither primitive) rewrites the index buffer on the
CPU into a pooled scratch buffer on every glDrawElements call and maps
that buffer with a GPU sync first. When the scratch buffer is already
referenced by the frame's command buffer, the draw flushes and calls
waitUntilCompleted on the render thread: a CPU/GPU round trip per shape
in normal use, and a permanent hang when the GPU stops executing work
(for example while an iOS app moves to the background).

Build the equivalent index lists once on the CPU instead:
VertexIndexArray::MakeTriangleFanAsTriangles() emits (0, i, i + 1) per
fan triangle and MakeLineLoopAsLineStrip() emits 0..n-1 followed by 0.
The same triangles and segments are rasterized, so output is unchanged.
The TriangleFan and LineLoop primitive types stay in Mesh for API
compatibility; nothing in libprojectM uses them any more.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant