OverrunGL - Overrun Game Library

Release version Snapshot version

Overview

void main() {
    // use MemorySegment to represent memory addresses
    MemorySegment window = glfwCreateWindow(
        800, 600,
        // use MemoryUtil::allocString to allocate string and manage by GC
        MemoryUtil.allocString("Title"),
        MemorySegment.NULL,
        MemorySegment.NULL
    );

    int width, height;
    // use Arena to allocate off-heap memory
    try (var arena = Arena.ofConfined()) {
        // use ValueLayout to represent memory layout
        var pWidth = arena.allocate(ValueLayout.JAVA_INT);
        var pHeight = arena.allocate(ValueLayout.JAVA_INT);

        glfwGetFramebufferSize(window, pWidth, pHeight);

        width = pWidth.get(ValueLayout.JAVA_INT, 0);
        height = pHeight.get(ValueLayout.JAVA_INT, 0);
    }

    // for OpenGL, create instance of wrappers
    var gl = new GL(GLFW::glfwGetProcAddress);
    // invoke OpenGL functions via instance methods
    gl.ClearColor(0.0f, 0.0f, 0.0f, 1.0f);
}

Introduction

Overrun Game Library is a high-performance library implemented with Java 25, which enables cross-platform access to a set of C library bindings, providing various useful utilities.

Comparing with LWJGL 3

LWJGL 3 is also a Java library that enables cross-platform access.

LWJGL 3.4.0 still uses JNI-style APIs, but delegates to the FFM backend when on JDK 25 or later. OverrunGL provides FFM-style APIs, where raw pointers are represented as MemorySegment.

Getting Started

You can check the wiki or the samples.

Feel free to ask questions in discussions in case you have trouble in setup works, such as environment configuring.

Import as a Dependency

The modules customizer is the recommended way to generate dependency declarations.

Maven coordinates for your information:

Maven coordinate of Bill of Materials: io.github.over-run:overrungl-bom
Maven coordinate of core module: io.github.over-run:overrungl
Others: io.github.over-run:overrungl-<module-name>

For example:

dependencies {
    implementation(platform("io.github.over-run:overrungl-bom:<VERSION>"))
    implementation("io.github.over-run:overrungl")
    implementation("io.github.over-run:overrungl-glfw")
    implementation(platform("org.lwjgl:lwjgl-bom:<VERSION>"))
    runtimeOnly("org.lwjgl:lwjgl-glfw::natives-<OS>-<ARCH>")
}

Using -SNAPSHOT Versions

We publish -SNAPSHOT versions frequently. You can check the list of available versions.

Add this maven repository to use snapshot versions:

repositories {
    maven("https://central.sonatype.com/repository/maven-snapshots")
}

Enable native access

The access to restricted methods must be enabled by adding a VM argument or a manifest attribute. The customizer can generate a list of modules to be enabled access.

--enable-native-access=overrungl.core,...

List of Supported Bindings

Khronos APIs

| Library | Description | |-------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | OpenGL | The most widely adopted 2D and 3D graphics API in the industry, bringing thousands of applications to a wide variety of computer platforms. | | Vulkan | A new generation graphics and compute API that provides high-efficiency, cross-platform access to modern GPUs used in a wide variety of devices from PCs and consoles to mobile phones and embedded platforms. |

Display and Input

| Library | Description | |----------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------| | GLFW | GLFW provides a simple API for creating windows, contexts and surfaces, receiving input and events. | | Native File Dialog Extended | A small C library that portably invokes native file open, folder select and file save dialogs. | | tinyfd | A native dialog library. |

Audio

| Library | Description | |-----------------------------------------|------------------------------------------------------------------------------------------------------------------------| | OpenAL | A cross-platform 3D audio API appropriate for use with gaming applications and many other types of audio applications. | | OpenAL Soft | An LGPL-licensed, cross-platform, software implementation of the OpenAL 3D audio API. |

Graphics

| Library | Description | |----------------------------------------------------------------------------------------------|----------------------------------------------------------------------------| | Shaderc | A collection of tools, libraries, and tests for Vulkan shader compilation. | | Vulkan Memory Allocator | Easy to integrate Vulkan memory allocation library |

stb - single-file public domain libraries for C/C++

| Library | Description | |-------------------|---------------------------------------------------------------------------------| | stb_easy_font | Quick-and-dirty easy-to-deploy bitmap font for printing frame rate, etc. | | stb_image | Image loading/decoding from file/memory: JPG, PNG, TGA, BMP, PSD, GIF, HDR, PIC | | stb_image_resize2 | Resize images larger/smaller with good quality. | | stb_image_write | Image writing to disk: PNG, TGA, BMP | | stb_perlin | Revised Perlin noise (3D input, 1D output). | | stb_rect_pack | Simple 2D rectangle packer with decent quality. | | stb_truetype | Parse, decode, and rasterize characters from truetype fonts. | | stb_vorbis | Decode ogg vorbis files from file/memory to float/16-bit signed output. |

Other

| Library | Description | |-----------------------------------------|-------------------------------------------------------| | JOML | A Java math library for OpenGL rendering calculations |

Release Notes

See doc/notes.

Additions

The latest Javadoc can be found here.

Overrungl

Install / Use

README