Package limn.backend

Interface Backend

All Superinterfaces:
AutoCloseable
All Known Implementing Classes:
LwjglBackend
public interface Backend extends AutoCloseable
Service-provider interface for a native platform backend (windows, input, GPU rendering, clipboard). The only shipped implementation is limn-backend-lwjgl (GLFW + OpenGL 3.3 core); the abstraction exists so ANGLE/Vulkan (or SDL) backends can replace it without touching any module above.

Lifecycle: construct on the process main thread (which becomes the UI thread), create windows, then runEventLoop() until the last window closes or stop() is called. The loop is event-driven: it sleeps in the native event wait and is woken by input, window damage or Ui.post(java.lang.Runnable).

  • Method Details

    • uiRuntime

      UiRuntime uiRuntime()
      Returns:
      the concurrency runtime owned by this backend

    • createWindow

      NativeWindow createWindow(WindowConfig config)
      Creates (but does not necessarily show) a native window. UI thread only.

    • runEventLoop

      void runEventLoop()
      Runs the event/render loop on the calling (UI) thread. Returns when the last window closes or stop() is invoked.

    • pushModal

      void pushModal(NativeWindow modal, NativeWindow parent)
      Registers modal as an active modal window and pushes it on the modal stack. Only the topmost modal receives input; every window it locks ignores input until it closes.

      Modality scope: a non-null parent makes it window-modal, so it locks only parent (and parent's owned popups), leaving unrelated windows interactive. A null parent makes it toolkit-modal, so it locks every other window. Modals stack: with several open, only the top one is usable and the non-modal windows are released only after the whole modal stack closes. UI thread only.

    • popModal

      void popModal(NativeWindow modal)
      Removes modal from the modal stack, releasing what it locked. UI thread only.

    • pushSceneModal

      Backend.SceneModalHandle pushSceneModal(NativeWindow owner, boolean toolkitScope)
      Registers an in-scene (overlay) modal hosted by owner. Unlike pushModal(limn.backend.NativeWindow, limn.backend.NativeWindow), there is no separate modal window: the overlay blocks owner's own content, so owner stays interactive, while this call blocks the same sibling windows a native modal would. toolkitScope true locks every other window; false locks only owner's owned popups. Release the returned handle when the overlay closes. UI thread only.

    • signalModalBlocked

      void signalModalBlocked()
      Gives the modal-blocked feedback (the alert sound plus a re-raise of the top modal) for an interaction the active modal ignores. The backend already does this for clicks on blocked native windows; call it for an in-scene modal's scrim so internal and native modals feel identical. UI thread only.

    • renderStats

      default RenderStats renderStats()
      Returns:
      aggregate GPU resource usage across all windows (texture count + estimated bytes), for diagnostics. Default: RenderStats.EMPTY. UI thread only.

    • render3DStats

      default Render3DStats render3DStats()
      Returns:
      aggregate 3D-subsystem GPU usage across all windows (meshes, textures, render targets, bytes, and last-frame draw calls/triangles), for diagnostics. Default: Render3DStats.EMPTY. UI thread only.

    • graphicsInfo

      default GraphicsInfo graphicsInfo()
      Returns:
      which graphics context this backend obtained and which optional capabilities it has: the report a bug about a machine that will not start, or that renders slowly, has to carry. The strings live on the context, so this is only answerable once createWindow(limn.backend.WindowConfig) has succeeded at least once; before that, and on a machine where it never does, the result carries the windowing platform and a GraphicsInfo.failure() instead. Default: GraphicsInfo.NONE. UI thread only.

    • displays

      default List<Display> displays()
      Returns:
      every connected Display, in the platform's order (index 0 is usually the primary). Empty when headless/embedded. UI thread only.

    • primaryDisplay

      default Display primaryDisplay()
      Returns:
      the primary Display, or null when headless. Default: the display that reports Display.isPrimary(), else the first of displays(). UI thread only.

    • fileDialogs

      default FileDialogs fileDialogs()
      Returns:
      the platform's native file/folder dialogs. Headless/embedded backends return FileDialogs.NONE (every dialog resolves empty, as if cancelled). UI thread only.

    • stop

      void stop()
      Asks the loop to exit. Safe to call from any thread.

    • close

      void close()
      Destroys all windows and releases native resources. UI thread only.
      Specified by:
      close in interface AutoCloseable