Package limn.backend.lwjgl

Class LwjglBackend

java.lang.Object
limn.backend.lwjgl.LwjglBackend
All Implemented Interfaces:
AutoCloseable, Backend
public final class LwjglBackend extends Object implements Backend
GLFW + OpenGL 3.3 core implementation of Backend.

Must be constructed on the process main thread (on macOS the JVM needs -XstartOnFirstThread); that thread becomes the Limn UI thread. The event loop is event-driven: it sleeps in glfwWaitEvents() (or glfwWaitEventsTimeout() when a delayed task is scheduled) and is woken by native events or by glfwPostEmptyEvent() whenever another thread posts through Ui.

Waking is not painting: the loop runs the tasks and then renders only the windows something asked a frame of, so an application whose posted task mutates a widget without invalidating it will not see the change.

  • Field Details

    • PLATFORM_PROPERTY

      public static final String PLATFORM_PROPERTY
      The windowing platform to ask GLFW for, which is only a question on Linux.

      Values: x11, wayland, any. Unset means the default below.

      See Also:

    • FORCE_IN_SCENE_POPUPS_PROPERTY

      public static final String FORCE_IN_SCENE_POPUPS_PROPERTY
      Set this to true to make every window report that it cannot be positioned, which puts menus and dropdowns into the owner scene on a platform that would otherwise place them in windows.

      It exists so the fallback can be looked at. Wayland is the only platform that really needs it, and a presentation that can only be seen on one desktop is one that gets broken on the other three and noticed a release later. With this the demo renders it anywhere, including into a --screenshot. It changes no behaviour the application chooses and none that a user can reach.

      See Also:

  • Constructor Details

    • LwjglBackend

      public LwjglBackend()

  • Method Details

    • uiRuntime

      public UiRuntime uiRuntime()
      Specified by:
      uiRuntime in interface Backend
      Returns:
      the concurrency runtime owned by this backend

    • fileDialogs

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

    • createWindow

      public NativeWindow createWindow(WindowConfig config)
      Description copied from interface: Backend
      Creates (but does not necessarily show) a native window. UI thread only.
      Specified by:
      createWindow in interface Backend

    • graphicsInfo

      public GraphicsInfo graphicsInfo()
      Specified by:
      graphicsInfo in interface Backend
      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 Backend.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.

    • runEventLoop

      public void runEventLoop()
      Description copied from interface: Backend
      Runs the event/render loop on the calling (UI) thread. Returns when the last window closes or Backend.stop() is invoked.
      Specified by:
      runEventLoop in interface Backend

    • pushModal

      public void pushModal(NativeWindow modal, NativeWindow parent)
      Description copied from interface: Backend
      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.

      Specified by:
      pushModal in interface Backend

    • popModal

      public void popModal(NativeWindow modal)
      Description copied from interface: Backend
      Removes modal from the modal stack, releasing what it locked. UI thread only.
      Specified by:
      popModal in interface Backend

    • pushSceneModal

      public Backend.SceneModalHandle pushSceneModal(NativeWindow owner, boolean toolkitScope)
      Description copied from interface: Backend
      Registers an in-scene (overlay) modal hosted by owner. Unlike Backend.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.
      Specified by:
      pushSceneModal in interface Backend

    • signalModalBlocked

      public void signalModalBlocked()
      Description copied from interface: Backend
      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.
      Specified by:
      signalModalBlocked in interface Backend

    • renderStats

      public RenderStats renderStats()
      Specified by:
      renderStats in interface Backend
      Returns:
      aggregate GPU resource usage across all windows (texture count + estimated bytes), for diagnostics. Default: RenderStats.EMPTY. UI thread only.

    • render3DStats

      public Render3DStats render3DStats()
      Specified by:
      render3DStats in interface Backend
      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.

    • displays

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

    • primaryDisplay

      public Display primaryDisplay()
      Specified by:
      primaryDisplay in interface Backend
      Returns:
      the primary Display, or null when headless. Default: the display that reports Display.isPrimary(), else the first of Backend.displays(). UI thread only.

    • stop

      public void stop()
      Description copied from interface: Backend
      Asks the loop to exit. Safe to call from any thread.
      Specified by:
      stop in interface Backend

    • close

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