MobileGL/docs/Disaggregated/guide/embedded-server.md

Embedding the split server in a host APK

A host application can load libMobileGL.so directly and hand the server an ANativeWindow it owns. The window, input and the Android Service lifecycle stay with the host APK; no MobileGL plugin APK is needed. The public interface is EmbeddedServer.h, uses only C types, and can also be called through dlsym. The build must enable MOBILEGL_BUILD_DISAGGREGATED.

Compositor service with a window

Before loading the library, set MOBILEGL_IPC_ROLE=server and MOBILEGL_IPC_DIAL=no, and clear MOBILEGL_TRANSPORT, MOBILEGL_IPC_SERVER_PATH, MOBILEGL_IPC_RING_MB and MOBILEGL_IPC_STAGE_MB. Running in a separate service process of the host APK is recommended, so that a rendering fault does not take down the UI process.

1. Call mobilegl_server_display_install_android(request_geometry, user). The callback may be null; when present it runs on the apply thread, must return quickly, and hands size changes to the host thread.
2. Take an ANativeWindow from the host's Surface and call mobilegl_server_display_attach_android(window, width, height). The server holds its own reference; the caller then releases its own. Attaching the same window again only updates the size.
3. On the service thread, call mobilegl_server_serve_inprocess("@anland-mobilegl-compositor"). This accepts one client session in the current process. The AF_UNIX control connection passes the shared-memory segment with SCM_RIGHTS, and data travels over a SHM ring. The client sets MOBILEGL_TRANSPORT=spawn, MOBILEGL_IPC_CONTROL=unix:@anland-mobilegl-compositor, MOBILEGL_IPC_DATA=shm and MOBILEGL_IPC_SURFACE=server.
4. When the Surface is destroyed, call mobilegl_server_display_detach(3000). The return values 0/1/2/3 mean no window, released directly, completed after the session released it, and timed out. On timeout the reference is kept until the apply thread stops using the window; losing the window currently ends the active session.
5. When the service stops, call mobilegl_server_stop_inprocess(), wait for the serve thread to return, then call mobilegl_server_display_uninstall(3000). The geometry callback's user object must live at least until then.

When width/height are zero, the Android attach queries the size from the ANativeWindow. A positive size in the geometry callback requests fixed buffer dimensions; 0/0 means restore the host's layout size, and the host reports the actual result through a later attach. Install, attach, detach and uninstall are serialized by the host. The library refuses to replace an installed display or an old window lease that has not ended, so that a late release cannot use another set of reference callbacks.

Concurrent off-screen application service

A process still has only one set of backend / GL state. A service with a window accepts a single compositor; other EGL clients can connect to the libMobileGLServer.so executable packaged by the host APK, which another service process starts and stops:

<nativeLibraryDir>/libMobileGLServer.so @anland-mobilegl --serve --max-sessions 16

--max-sessions is the limit on active sessions; it accepts 1..64 and still defaults to 1. Values above 1 apply only to the AF_UNIX --serve off-screen supervisor. Each client forks its own worker with an independent backend, isolated from other sessions in shared memory; a worker returning frees its slot, and all workers end when the supervisor ends. These workers have no display; the client should clear MOBILEGL_IPC_SURFACE and submit window images through its own WSI.

Process isolation solves multiple applications connecting at the same time; true multi-context / share-group support inside one application still needs separate work.