DOCSEARCHbyAlgolia
Submit Docs

Lightweight Java Game Library 3

repository·master·Indexed 26 days ago

https://github.com/lwjgl/lwjgl3

A high-performance Java library providing low-level, cross-platform access to native APIs including OpenGL, Vulkan, OpenAL, and OpenCL. It offers bindings for Khronos APIs, window management (GLFW, SDL), audio (FMOD, OpenAL), and various graphics and system utility libraries. Version 3.4.0 introduces support for the Foreign Function & Memory (FFM) API for JDK 25, providing an alternative to JNI and sun.misc.Unsafe.

Tokens
17.1K
Snippets
10
Records
169
Agent score
89%

What's inside LWJGL 3

  1. Overview of LWJGL 3

    master

    LWJGL (Lightweight Java Game Library 3) is a high-performance Java library providing direct, cross-platform access to native APIs. It is designed for graphics (OpenGL/Vulkan), audio (OpenAL), and parallel computing (OpenCL).

    Note: LWJGL is a low-level enabling technology, not a high-level game engine or framework. It provides direct access to native libraries wrapped in a type-safe Java layer. Novice programmers are encouraged to use game engines that utilize LWJGL rather than working with the library directly.

  2. Understand LWJGL Project Modules

    master

    The LWJGL project is organized into several distinct modules that serve different purposes in the development lifecycle:

    • lwjgl: The core library containing the LWJGL bindings and generated code. This is the primary module used for application development.
    • samples: A suite of demo and benchmarking applications used to showcase LWJGL capabilities.
    • generator: The source code generator and build tools. This module is used exclusively for building LWJGL itself and has no runtime dependency for end-users.
    • extract: An experimental tool used to extract generator templates from native headers.

  3. Add a new binding to LWJGL

    master

    To add a new binding, start by copying the structure of an existing binding in modules/lwjgl/. You must then update several configuration files to register the new module:

    In the lwjgl3 repository:

    • build.xml: Add compileBinding tag, compile-tests demo packages, and release-module tag.
    • config/build-bindings.xml: Add binding.<name> property and update the forEachBinding macro.
    • config/<platform>/build.xml: Add the build definition for applicable platforms.
    • config/tests.xml: Add the test package.
    • modules/generator/src/main/kotlin/org/lwjgl/generator/Generator.kt: Add to the Binding enum.
    • README.MD: Add to the 'List of Supported Bindings'.
    • doc/notes/<version>.md: Add to the next version release notes.
    • build.gradle: Add to the Artifacts enum.
    • IDEA project (optional): Add Java and Kotlin modules to .idea/modules.xml.

    In the lwjgl3-www repository:

    • client/routes/customize/BuildConfigurator/lwjgl/nightly.js: Add the binding definition.

  4. Use FMOD Bindings

    master

    FMOD bindings were added in version 3.3.2.

    Important: Native binaries are not included in the LWJGL distribution because the FMOD license does not permit redistribution. You must download the FMOD native libraries separately and deploy them alongside your application.

  5. Migrate to LWJGL 3.0.0 Beta

    master

    The 3.0.0 Beta release marked the transition to a stable API. When migrating from earlier versions (like 3.0.0a), be aware of the following breaking changes:

    • API Stability: The API is now considered stable, but significant changes were made to struct and callback classes.
    • Package Restructuring: Advanced functionality has been moved from the base package to the org.lwjgl.system package. Note that the public API in the system package may change between releases.
    • Memory Management: An explicit memory management API was introduced. You can also enable a debug allocator to report memory leaks with full stack-traces.
    • Type Safety (Structs vs ByteBuffers): Bindings no longer use ByteBuffer for struct-related parameters and return values. Instead, they use Struct and StructBuffer implementations to improve type safety.
    • Configuration: Use the Configuration class to programmatically configure LWJGL.

  6. Use Windows architecture-specific native JARs

    master

    On Windows, native JAR files are now separated by architecture. Use the appropriate Maven classifier to ensure you load the correct shared libraries:

    • x64 (Default): Use the windows classifier.
    • x86: Use the windows-x86 classifier (contains lwjgl-natives-windows-x86.jar).

  7. Initialize Vulkan Memory Allocator (VMA) bindings

    master

    The VMA native library is not initialized automatically. To use the VMA bindings, you must manually trigger the loading of the native library by calling Class.forName before use.

    Class.forName("org.lwjgl.util.vma.LibVma");

  11. Use versioned class inheritance for bindings

    master

    In recent versions (starting from 3.4.x), versioned classes in bindings (such as AL, ALC, CL, EGL, GL, GLES, GLX, and VK) now form inheritance hierarchies. For example, GL30 extends GL21, which extends GL20.

    When you import a specific versioned class, all symbols from previous versions are automatically available through inheritance. You no longer need to import multiple versioned classes to access older symbols.