Merge pull request #10 from Over-Run/0.1.0

1009: OGL 102: Version: 0.1.0

.editorconfig

@@ -11,5 +11,5 @@ insert_final_newline = true
 [*.md]
 trim_trailing_whitespace = false
 
-[{*.yml, *.json}]
+[{*.yml,*.json}]
 indent_size = 2

.github/workflows/gradle.yml

@@ -14,7 +14,7 @@ jobs:
     strategy:
       matrix:
         java: [
-          20
+          21-ea
         ]
         os: [ ubuntu-latest, windows-latest ]
     runs-on: ${{ matrix.os }}
@@ -33,7 +33,7 @@ jobs:
         with:
           arguments: build
       - name: capture build artifacts
-        if: ${{ runner.os == 'Linux' && matrix.java == '20' }}
+        if: ${{ runner.os == 'Linux' && matrix.java == '21-ea' }}
         uses: actions/upload-artifact@v3
         with:
           name: Artifacts

CONTRIBUTING.md

@@ -4,27 +4,26 @@ You are welcome to contribute to OverrunGL.
 
 ## Code of Conduct
 
-You must abide by the [Code of Conduct](CODE_OF_CONDUCT.md).
+You must respect the [Code of Conduct](CODE_OF_CONDUCT.md).
 
 ## Issues
 
 To start with [issues](https://github.com/Over-Run/overrungl/issues), we recommend you to use the issue template.
 
 ## Pull Requests
 
-The pull requests will be reviewed in 1-2 workweeks. Please note that the code must be formatted.
+The pull requests will be reviewed in 1-5 workweeks. Please note that the code must be formatted.
 
 ### Formatted Code
 
 The formatted code:
 
-- Java files header **MUST** contain the copy [LICENSE](LICENSE). The copy **MUST** be ended without empty line and commented with block style.
-- Class names **MUST** be CamelCase
-- Method and field names _should_ be camelCase
-- File encoding **MUST** be UTF-8
-- File line separator **MUST** be LF
-
-Some rules are configured with [.editorconfig](.editorconfig).
+- Except auto-generated files, Java files header **MUST** contain the copy [LICENSE](LICENSE). The copy **MUST** be ended without empty line and commented with block style;
+- The class names **MUST** be CamelCase;
+- The method and field names _should_ be camelCase;
+- The file encoding **MUST** be UTF-8;
+- The file line separator **MUST** be LF;
+- Other rules specified by [.editorconfig](.editorconfig).
 
 Example:
 
@@ -54,5 +53,5 @@ public class Example /* Space */ {
 
 ## Discussions
 
-You can visit our [forum](https://github.com/Over-Run/overrungl/discussions) and create your post, sharing your experience
+You can visit our [forum](https://github.com/Over-Run/overrungl/discussions) and create your post, share your experience
 or just ask some questions.

README.md

@@ -11,7 +11,7 @@
 
 ## Introduction
 
-Overrun Game Library is a high performance library that implemented with Java 20,
+Overrun Game Library is a high-performance library that implemented with Java 21,
 enables cross-platform access to a set of C/C++ library bindings, and provides some useful utilities.
 
 ### OverrunGL vs. LWJGL
@@ -24,12 +24,12 @@ performance.
 ## Getting Started
 
 You can check our [wiki](https://github.com/Over-Run/overrungl/wiki) or
-the [samples](modules/samples/src/test/java/org/overrun/glib/demo).
+the [samples](modules/samples/src/test/java/org/overrun/gl/demo).
 
 ## Using as a Dependency
 
 ~~The libraries are available on Maven Central.~~ Currently, we are developing with the first version, and it is very
-unstable, so you have to use the -SNAPSHOT version.
+unstable, so you have to use `-SNAPSHOT` version.
 
 You can import with `io.github.over-run:overrungl-bom:{the version}` and other submodules.
 
@@ -47,15 +47,36 @@ and include this maven repository:
 maven { url "https://s01.oss.sonatype.org/content/repositories/snapshots" }
 ```
 
-## Supported Bindings
+## List of Supported Bindings
 
-Basic graphics:
+### Khronos APIs
 
-| Module | Functionality                         |
-|--------|---------------------------------------|
-| GLFW   | Full (Core and native)                |
-| OpenGL | Partial (Core and partial extensions) |
-| STB    | Partial (Image, perlin noise)         |
+| Library                                   | Description                                                                                                                                 |
+|-------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|
+| [OpenGL](https://www.khronos.org/opengl/) | The most widely adopted 2D and 3D graphics API in the industry, bringing thousands of applications to a wide variety of computer platforms. |
+
+### Display and Input
+
+| Library                                                                          | Description                                                                                                                                                                                                                                |
+|----------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| [GLFW](http://www.glfw.org/)                                                     | Create multiple windows, handle user input (keyboard, mouse, gaming peripherals) and manage contexts. Also features multi-monitor support, clipboard access, file drag-n-drop, and [much more](http://www.glfw.org/docs/latest/news.html). |
+| [Native File Dialog Extended](https://github.com/btzy/nativefiledialog-extended) | A small C library that portably invokes native file open, folder select and file save dialogs.                                                                                                                                             |
+
+### [stb](https://github.com/nothings/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_resize | 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).                                     |
+
+### Other
+
+| Library                                 | Description                                           |
+|-----------------------------------------|-------------------------------------------------------|
+| [JOML](https://github.com/JOML-CI/JOML) | A Java math library for OpenGL rendering calculations |
 
 ## Contact
 
@@ -68,7 +89,7 @@ See [doc/notes](doc/notes/README.md).
 
 ## Additional
 
-OpenGL docs can be found [here](https://docs.gl/).
+The documentation of OpenGL can be found [here](https://docs.gl/).
 
 ### Publishing (for internal member)
 
@@ -94,10 +115,26 @@ natives
 │  │  └─ x64
 │  │     └─ libglfw3.dylib
 │  └─ windows
-│     ├─ x64
-│     │  └─ glfw3.dll
-│     └─ x86
+│     └─ x64
 │        └─ glfw3.dll
+├─ nfd https://github.com/Over-Run/nativefiledialog-extended-ci
+│  ├─ linux
+│  │  ├─ arm32
+│  │  │  └─ libnfd.so
+│  │  ├─ arm64
+│  │  │  └─ libnfd.so
+│  │  └─ x64
+│  │     └─ libnfd.so
+│  ├─ os x
+│  │  ├─ arm64
+│  │  │  └─ libnfd.dylib
+│  │  └─ x64
+│  │     └─ libnfd.dylib
+│  └─ windows
+│     ├─ arm64
+│     │  └─ nfd.dll
+│     └─ x64
+│        └─ nfd.dll
 └─ stb https://github.com/Over-Run/stb-ci
    ├─ linux
    │  ├─ arm32
@@ -114,8 +151,6 @@ natives
    └─ windows
       ├─ arm64
       │  └─ stb.dll
-      ├─ x64
-      │  └─ stb.dll
-      └─ x86
+      └─ x64
          └─ stb.dll
 ```

build.gradle

@@ -13,7 +13,6 @@ for (Artifact module : Artifact.VALUES) {
 project(":samples").ext.subName = "samples"
 
 enum NativePlatform {
-    WIN_32("windows", "x86", "windows-x86", "", ".dll", "Win32"),
     WIN_64("windows", "x64", "windows", "", ".dll", "Win64"),
     WIN_ARM64("windows", "arm64", "windows-arm64", "", ".dll", "WinArm64"),
     LINUX_64("linux", "x64", "linux", "lib", ".so", "Linux64"),
@@ -68,9 +67,10 @@ enum NativePlatform {
 
 enum NativeBinding {
     GLFW("glfw", "glfw3",
-        NativePlatform.WIN_32, NativePlatform.WIN_64,
+        NativePlatform.WIN_64,
         NativePlatform.LINUX_64, NativePlatform.LINUX_ARM64,
         NativePlatform.MACOS, NativePlatform.MACOS_ARM64),
+    NFD("nfd", "nfd", NativePlatform.ALL),
     STB("stb", "stb", NativePlatform.ALL),
 
     private final String name
@@ -107,6 +107,9 @@ enum Artifact {
     JOML('overrungl-joml', 'OverrunGL - JOML native access',
         'A Java math library for OpenGL rendering calculations',
         ':joml', 'Joml'),
+    NFD('overrungl-nfd', 'OverrunGL - Native File Dialog',
+        'A tiny, neat C library that portably invokes native file open and save dialogs.',
+        ':nfd', 'Nfd', NativeBinding.NFD),
     OPENGL("overrungl-opengl", "OverrunGL - OpenGL bindings",
         "The most widely adopted 2D and 3D graphics API in the industry, bringing thousands of applications to a wide variety of computer platforms.",
         ":opengl", "Opengl"),
@@ -188,7 +191,7 @@ subprojects {
         }
     }
 
-    def targetJavaVersion = 20
+    def targetJavaVersion = 21
     tasks.withType(JavaCompile).configureEach {
         options.encoding = 'UTF-8'
         options.compilerArgs += '--enable-preview'

doc/notes/0.x/0.1.0.md

@@ -9,13 +9,5 @@ This version includes the following features:
 - OpenGL Loader
 - STB Image, perlin noise, easy font
 - C memory function
-- Growable buffer
 - Native memory access for JOML
-
-These features are purposed to target:
-
-- OpenGL extensions
-
-These features are candidates:
-
-- STB true-type
+- Native File Dialog Extended

doc/notes/README.md

@@ -1,19 +1,3 @@
 ## Version History
 
 - [0.x](0.x/README.md)
-
-### Features
-
-These features are purposed to target:
-
-- (0.1.0) OpenGL 307 extensions
-
-These features are candidates:
-
-- (0.1.0) STB true-type
-
-### Drafts
-
-These features are drafts. The contents are subject to change until release.
-
-- ?

gradle/wrapper/gradle-wrapper.properties

@@ -1,6 +1,6 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-8.1-rc-1-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.2-bin.zip
 networkTimeout=10000
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists

modules/overrungl/core/src/main/java/org/overrun/glib/Addressable.java → modules/overrungl/core/src/main/java/org/overrun/gl/Addressable.java

@@ -12,17 +12,9 @@
  *
  * The above copyright notice and this permission notice shall be included in all
  * copies or substantial portions of the Software.
- *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
- * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
- * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
- * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
- * SOFTWARE.
  */
 
-package org.overrun.glib;
+package org.overrun.gl;
 
 import java.lang.foreign.MemorySegment;
 
@@ -35,9 +27,7 @@
 @FunctionalInterface
 public interface Addressable {
     /**
-     * The address value.
-     *
-     * @return the address
+     * {@return the raw address value}
      */
     MemorySegment address();
 }

modules/overrungl/core/src/main/java/org/overrun/gl/ArrayPointer.java

@@ -0,0 +1,38 @@
+/*
+ * MIT License
+ *
+ * Copyright (c) 2023 Overrun Organization
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ */
+
+package org.overrun.gl;
+
+import java.lang.foreign.SequenceLayout;
+
+/**
+ * An array pointer.
+ *
+ * @author squid233
+ * @since 0.1.0
+ */
+public interface ArrayPointer extends Addressable {
+    /**
+     * {@return the count of the elements in this array}
+     */
+    default long elementCount() {
+        if (this instanceof Struct struct &&
+            struct.layout() instanceof SequenceLayout sequenceLayout) {
+            return sequenceLayout.elementCount();
+        }
+        throw new UnsupportedOperationException();
+    }
+}

modules/overrungl/core/src/main/java/org/overrun/glib/Callback.java → modules/overrungl/core/src/main/java/org/overrun/gl/Callback.java

@@ -14,7 +14,7 @@
  * copies or substantial portions of the Software.
  */
 
-package org.overrun.glib;
+package org.overrun.gl;
 
 import java.lang.foreign.Arena;
 import java.lang.foreign.FunctionDescriptor;
@@ -41,14 +41,12 @@ default MemorySegment address(Arena arena) {
     }
 
     /**
-     * Returns the function descriptor of this callback.
-     *
-     * @return the function descriptor
+     * {@return the function descriptor of this callback}
      */
     FunctionDescriptor descriptor();
 
     /**
-     * Find the method handle from the given method handles lookup.
+     * Finds the method handle from the given method handles lookup.
      *
      * @param lookup the lookup
      * @return the method handle
@@ -65,10 +63,9 @@ default MemorySegment address(Arena arena) {
      * @param function the function descriptor.
      * @return the memory segment.
      */
-    default MemorySegment segment(Arena arena,
-                                  FunctionDescriptor function) {
+    default MemorySegment segment(Arena arena, FunctionDescriptor function) {
         try {
-            return RuntimeHelper.LINKER.upcallStub(handle(MethodHandles.publicLookup()).bindTo(this), function, arena.scope());
+            return RuntimeHelper.LINKER.upcallStub(handle(MethodHandles.publicLookup()).bindTo(this), function, arena);
         } catch (NoSuchMethodException | IllegalAccessException e) {
             throw new RuntimeException(e);
         }