Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/LWJGL/lwjgl3/llms.txt

Use this file to discover all available pages before exploring further.

LWJGL 3 offers five bindings that handle window creation, user input, and native file dialogs. GLFW is the primary choice for most applications, while SDL provides a broader platform abstraction. JAWT, Native File Dialog Extended, and tinyfd fill specialized roles for AWT integration and file-picker dialogs.
The current stable release is 3.4.2. Use the LWJGL build configurator to generate dependency declarations for the bindings you need.

GLFW

Maven artifact: org.lwjgl:lwjgl-glfw
Key classes: GLFW, GLFWVidMode, GLFWWindowSizeCallback, GLFWErrorCallback, Callbacks
GLFW is the primary windowing and input library for LWJGL applications. It lets you create multiple windows, manage OpenGL/Vulkan contexts, handle keyboard, mouse, and gamepad input, and access multi-monitor setups — all through a clean, cross-platform API. Capabilities:
FeatureNotes
Window creationMultiple windows, resizable or fixed-size, with or without decorations
Context managementOpenGL and Vulkan surface creation; context sharing between windows
Keyboard inputKey codes, scancode access, key callbacks, text input via char callbacks
Mouse inputCursor position, buttons, scroll wheel, raw motion mode
Gamepad / joystickAxis and button polling; gamepad mapping via SDL_GameControllerDB
Monitor supportEnumerate displays, query video modes, switch to fullscreen
ClipboardRead and write system clipboard as UTF-8 text
File drag-and-dropReceive dropped file paths via a callback
Minimal window example:
// Initialize GLFW
if (!GLFW.glfwInit()) throw new IllegalStateException("Unable to initialize GLFW");

// Create a window
GLFW.glfwDefaultWindowHints();
GLFW.glfwWindowHint(GLFW.GLFW_VISIBLE, GLFW.GLFW_FALSE);
long window = GLFW.glfwCreateWindow(1280, 720, "My App", 0L, 0L);

// Set up an OpenGL context and enter the render loop
GLFW.glfwMakeContextCurrent(window);
GL.createCapabilities();
GLFW.glfwShowWindow(window);

while (!GLFW.glfwWindowShouldClose(window)) {
    GL11.glClear(GL11.GL_COLOR_BUFFER_BIT);
    GLFW.glfwSwapBuffers(window);
    GLFW.glfwPollEvents();
}

Callbacks.glfwFreeCallbacks(window);
GLFW.glfwDestroyWindow(window);
GLFW.glfwTerminate();
For Vulkan applications, use GLFW.glfwCreateWindowSurface() to create a VkSurfaceKHR from a GLFW window handle. Query the required instance extensions with GLFWVulkan.glfwGetRequiredInstanceExtensions().

SDL

Maven artifact: org.lwjgl:lwjgl-sdl
Key classes: SDL, SDLVideo, SDLEvents, SDLGamepad, SDLAudio, SDLRenderer
Simple DirectMedia Layer (SDL) is a cross-platform development library providing low-level access to audio, keyboard, mouse, joystick, and graphics hardware via OpenGL, Direct3D, Metal, and Vulkan. The LWJGL binding exposes SDL 3. When to choose SDL over GLFW:
  • You need SDL’s built-in audio subsystem or software renderer
  • Your application targets platforms with strong SDL ecosystem support (consoles via official SDL ports)
  • You want a single library that also handles audio and thread primitives
  • You are porting an existing SDL application
SDL subsystems available through LWJGL:
SubsystemDescription
VideoWindow creation, OpenGL/Vulkan context, display enumeration
EventsUnified event queue for all input devices
GamepadModern gamepad API with SDL_GameControllerDB mapping
JoystickLow-level joystick access
AudioDevice enumeration, stream-based audio output
Renderer2D accelerated software/hardware renderer
TimerHigh-resolution timer and delay utilities
SDL and GLFW overlap significantly in windowing and input. Most LWJGL projects use GLFW because it integrates more cleanly with the LWJGL OpenGL/Vulkan context utilities. Choose SDL when you need its broader hardware abstraction or audio subsystem.

JAWT

Maven artifact: org.lwjgl:lwjgl-jawt
Key classes: JAWT, JAWTDrawingSurface, JAWTDrawingSurfaceInfo
JAWT is the Java AWT Native Interface — a standard part of the JDK that exposes native window handles for AWT components. The LWJGL binding wraps this interface so you can retrieve a native handle (HWND on Windows, Window on X11, NSView on macOS) from a Swing or AWT Canvas and use it to create an OpenGL or Vulkan context inside a traditional Java GUI application. Typical use cases:
  • Embedding an OpenGL viewport inside a Swing application (e.g., a level editor or 3D modelling tool)
  • Rendering Vulkan output into an AWT panel alongside standard Java Swing widgets
  • Interoperating with Java UI frameworks that manage their own window lifecycle
JAWT integration adds complexity around event dispatch thread (EDT) coordination and platform-specific rendering contexts. For new projects, consider a standalone GLFW window instead of JAWT unless you specifically need Swing/AWT coexistence.

Native File Dialog Extended

Maven artifact: org.lwjgl:lwjgl-nfd
Key classes: NativeFileDialog, NFDFilterItem
Native File Dialog Extended (NFD) is a small C library that portably invokes native OS file-open, folder-select, and file-save dialogs. Unlike cross-platform UI toolkits that draw their own dialog, NFD delegates to the platform’s real file picker — matching the user’s OS theme and behaviour exactly. Supported dialog types:
MethodDescription
NativeFileDialog.NFD_OpenDialogSingle-file open picker
NativeFileDialog.NFD_OpenDialogMultipleMulti-file open picker
NativeFileDialog.NFD_SaveDialogSave-file dialog with default filename
NativeFileDialog.NFD_PickFolderFolder/directory picker
File filter example:
// Build a filter for image files
try (MemoryStack stack = MemoryStack.stackPush()) {
    NFDFilterItem.Buffer filters = NFDFilterItem.malloc(2, stack);
    filters.get(0).name(stack.UTF8("Image files")).spec(stack.UTF8("png,jpg,bmp"));
    filters.get(1).name(stack.UTF8("All files")).spec(stack.UTF8("*"));

    PointerBuffer outPath = stack.mallocPointer(1);
    int result = NativeFileDialog.NFD_OpenDialog(outPath, filters, (CharSequence) null);
    if (result == NativeFileDialog.NFD_OKAY) {
        String path = outPath.getStringUTF8(0);
        NativeFileDialog.NFD_FreePath(outPath.get(0));
    }
}
Always call NativeFileDialog.NFD_Init() once at startup and NativeFileDialog.NFD_Quit() at shutdown to properly manage COM initialization on Windows.

tinyfd

Maven artifact: org.lwjgl:lwjgl-tinyfd
Key classes: TinyFileDialogs
tinyfd (tiny file dialogs) is a native dialog library that provides file pickers, message boxes, color choosers, input prompts, and notification popups through a single, simple API. It falls back gracefully across platforms — using Zenity/kdialog on Linux, native dialogs on Windows and macOS. Available dialogs:
MethodDescription
TinyFileDialogs.tinyfd_openFileDialogSingle or multi-file open dialog
TinyFileDialogs.tinyfd_saveFileDialogFile save dialog
TinyFileDialogs.tinyfd_selectFolderDialogFolder picker
TinyFileDialogs.tinyfd_messageBoxOK / OK-Cancel / Yes-No message box
TinyFileDialogs.tinyfd_inputBoxSingle-line text input dialog
TinyFileDialogs.tinyfd_colorChooserColor picker dialog
TinyFileDialogs.tinyfd_notifyPopupSystem notification/toast
Compared to NFD:
FeaturetinyfdNFD Extended
File open/save dialogsYesYes
Folder pickerYesYes
Message / input boxesYesNo
Color pickerYesNo
Native look on all platformsVaries (uses scripts on Linux)Yes
Multi-selectYesYes
For strictly file/folder dialogs, NFD Extended provides a more consistent native appearance. Use tinyfd when you also need message boxes, input prompts, or color pickers without pulling in a larger UI library.

Build docs developers (and LLMs) love