Skip to content

Update readme: fork main points and usage examples (issue 8) #15

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
EndrII merged 2 commits into from
Oct 13, 2026
Merged

Update readme: fork main points and usage examples (issue 8) #15

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b0b2072
Update readme: fork main points, C/C++/CMake usage examples (issue 8)
QuasarAppCI Oct 13, 2026
4e3bf08
Merge remote-tracking branch 'origin/main' into task_8
QuasarAppCI Oct 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
204 changes: 95 additions & 109 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,22 @@

Successors to OpenSimplex Noise, plus updated OpenSimplex. Includes 2D, 3D, and 4D noise.

## About this fork

This is the QuasarApp community fork of
[KdotJPG/OpenSimplex2](https://github.com/KdotJPG/OpenSimplex2).

- **Performance oriented — C only.** The OpenSimplex2 method is performance
oriented, so this fork allows only the C implementation — because it is the
most powerful. The C implementation is the single original, most fast and
safe implementation of the noise.
- **The Rust implementation was removed.** The Rust implementation was still
slow and used a 32 bit source, so it may break high quality results.
- **Why a fork?** The maintainers of the original repository are not active
and do not fix currently critical bugs.
- **Other languages?** If you need an implementation in another language, just
create a simple wrapper around the C API and create a Merge Request.

## Motivation

Legacy OpenSimplex used a different grid layout scheme to Simplex. It worked fine for common applications, but didn't produce as consistent contrast as the original Simplex point layout in 3D/4D. It also broke down completely when extended to 5D+, producing diagonal bands of visibly-varying value ranges.
Expand All @@ -17,148 +33,118 @@ Gradient vector tables were also revisited to improve probability symmetry in bo
* Is about as fast as common Simplex implementations.
* 3D is implemented by constructing a rotated body-centered-cubic grid as the offset union of two rotated cubic grids, and finding the closest two points on each.
* 4D is implemented using 5 offset copies of the dual (reverse-skewed) grid to produce the target grid. This technique generalizes to any number of dimensions.
* Bundled 2D function is just 2D Simplex with a nice gradient table. The 4D technique does extend to 2D, but this was found to be faster and I couldn't find evidence of limitations on its use. 3D and 4D are novel contributions to the field.
* The bundled 2D function is just 2D Simplex with a nice gradient table.
* The C implementation provides the OpenSimplex2(F) noise in 2D, 3D and 4D.

### OpenSimplex2S
* Looks the most like 2014 OpenSimplex.
* Uses large vertex contribution ranges like 2014 OpenSimplex, but has better uniformity in 3D and 4D.
* 3D is implemented analogously to OpenSimplex2(F), but finds the closest four points on each to match the larger radius.
* 4D is implemented using the ordinary skew and a pre-generated 4x4x4x4 lookup table. I have a work-in-progress more-procedural implementation in my project backlog, which I will swap in if I find it to be competitive in performance.
* 2D is based on Simplex, but uses a different process to find which points are in range.
* Recommended choice for ridged noise (if passing individual layers into `abs(x)`).
* Available in the GLSL and HLSL shader implementations.
### Shaders

Note: area-generators have been moved to [their original repository](https://github.com/KdotJPG/Noise-VertexQueue-AreaGen).
The `glsl/` and `hlsl/` directories provide GLSL and HLSL shader versions of
OpenSimplex2(F) and OpenSimplex2S. OpenSimplex2S looks the most like 2014
OpenSimplex: it uses large vertex contribution ranges, but has better
uniformity in 3D and 4D, and is the recommended choice for ridged noise.

## C usage
## Usage

The C implementation is the main implementation of the noise generator.
The source (`OpenSimplex2F.c`) and the public header (`OpenSimplex2F.h`)
are located at the root of this repository.

### Manual usage

Compile the source file into your project with your C compiler, for example:

```
cc -Wall -Wextra --pedantic -O3 -c OpenSimplex2F.c -lm
```
### C

Or use the bundled Makefile:
```c
#include <OpenSimplex2F.h>

```
make
/* Allocate and initialize the noise context (0 on success). */
struct OpenSimplex2F_context *ctx = NULL;
if (OpenSimplex2F(42, &ctx) != 0) {
/* context creation failed */
return 1;
}

/* 2D, 3D and 4D noise, each in several lattice orientations. */
double n2 = OpenSimplex2F_noise2(ctx, 0.5, 0.5);
double n3 = OpenSimplex2F_noise3_XYBeforeZ(ctx, 0.5, 0.5, 0.5);
double n4 = OpenSimplex2F_noise4_XYBeforeZW(ctx, 0.5, 0.5, 0.5, 0.5);

/* Release the context and the singleton lattice point data. */
OpenSimplex2F_free(ctx);
OpenSimplex2F_shutdown();
```

The Makefile also builds the `test_OpenSimplex2F` binary (test source in
`tests/test_OpenSimplex2F.c`), which writes
2D/3D/4D noise images (requires libpng).
### C++

### CMake
The header is C-compatible (`extern "C"` guarded), so the same API can be
used directly from C++:

To include the library in your own CMake project, simply add the subdirectory and link the OpenSimplex2 interface target:
```cpp
#include <OpenSimplex2F.h>

```cmake
add_subdirectory(submodules/OpenSimplex2)
target_link_libraries(${CURRENT_PROJECT} PUBLIC OpenSimplex2Interface)
struct OpenSimplex2F_context *ctx = nullptr;
if (OpenSimplex2F(42, &ctx) == 0) {
double value = OpenSimplex2F_noise3_XYBeforeZ(ctx, x, y, z);
/* ... */
OpenSimplex2F_free(ctx);
}
OpenSimplex2F_shutdown();
```

The OpenSimplex2 interface target links the C implementation.
### CMake

To build the tests, keep the `OPENSIMPLEX2_TESTS` option enabled (default
`ON`) and run the `test` target — it builds the `OpenSimplex2tests`
executable from the `tests/` subdirectory and runs it (the targets are
registered with the `addTests()` function of the QuasarApp CMake module):
To include the library in your own CMake project, add the repository as a
subdirectory — for example as a git submodule:

```
cmake -B build
cmake --build build
cmake --build build --target test
git submodule add https://github.com/QuasarApp/OpenSimplex2.git third_party/OpenSimplex2
```

### Including in C/C++ Projects

```c
#include <OpenSimplex2F.h>
```

**Note:**
The C implementation provides the OpenSimplex2(F) noise in 2D, 3D and 4D.
The GLSL and HLSL directories provide shader versions of OpenSimplex2(F)
and OpenSimplex2S.

## Changelog
and link the `OpenSimplex2Interface` target in your `CMakeLists.txt`:

* C implementation is now the main implementation, moved from `_old` to the root of the repository. All other implementations (Rust, C#, Java, C++) and the `_old` archive were removed. (Oct 10, 2026)
* Rust implementation optimisations and CMake Inteface implementation (Nov 12, 2025)
* Tuned up this `README.md`. (Mar 26, 2022)
* Re-wrote functions to be instancelessly seedable and less dependent on lookup tables. Re-organized repository. Renamed `OpenSimplex2F` to just `OpenSimplex2` in file/class names. (Jan 16, 2022)
* Shortened lookup table for Simplex/OpenSimplex2(F) 4D (July 5, 2020)
* Added 4D to OpenSimplex2(F) Java/C#, port OpenSimplex2S 4D to C#. (July 5, 2020)
* Added 4D to OpenSimplex2S Java. (Apr 30, 2020)
* Replaced individual renders in `README.md` with consolidated renders. (Feb 10, 2020)
* Replaced 12-direction 2D gradient set with a 24-direction set, to reduce visible feature repetition in thresholded single-octave 2D noise. (Feb 10, 2020)
* Renamed filenames FastSimplexStyleNoise to OpenSimplex2F, and SuperSimplexNoise to OpenSimplex2S. (Feb 10, 2020)
* Moved legacy OpenSimplex into legacy directories. (Feb 10, 2020)
* Slightly reorganized description above, and added TODO/changelog. (Jan 23, 2020)
* Renamed / additionally named the noise "OpenSimplex (2.0)", separated into two versions/variants. (Jan 23, 2020)
* SuperSimplex and FastSimplexStyleNoise are very similar to each other algorithmically, and are in the same spirit as the original OpenSimplex.
* OpenSimplex is used in a lot of projects, and the naming might help facilitate adoption of the new noise in its place.
* Add C# ports of evaluators. (Jan 13, 2020)
* Create separate files which include area generators. (Jan 13, 2020)
* Renamed PlaneFirst evaluators to XYBeforeZ, and added XZBeforeY. (Jan 13, 2020)
* Fixed equals() method in AreaGenLatticePoint3D for area generators. (Dec 24, 2019)

## Renders

### 2D Noise

![Renders 2D](https://user-images.githubusercontent.com/8829856/149676975-ba7cfc82-3bb5-4e0c-b6cb-8315eca51193.png)

* OpenSimplex2S is a smoother copy of OpenSimplex2(F).
* OpenSimplex2S and Updated OpenSimplex are effectively identical.
* Original OpenSimplex produced more straight parts and was not as probabilistically symmetric.

### 3D Noise (ImproveXY Orientation)

![Renders 3D ImproveXY](https://user-images.githubusercontent.com/8829856/149676980-768775b4-f0ca-417b-aa0a-2379b61fb69d.png)

* OpenSimplex2(F) and OpenSimplex2S, 2D slices of 3D ImproveXY, keep mostly the same properties as you move along the third axis.
* Updated OpenSimplex looks good in both slices, but the slices look different from each other. In an animation, this is particularly noticeable.
* Original OpenSimplex was less uniform and not as probabilistically symmetric.

### 3D Noise (Fallback Orientation)

![Renders 3D Fallback](https://user-images.githubusercontent.com/8829856/149676981-2d40fff9-b585-4fca-9a09-eb51d5927fec.png)

* OpenSimplex2(F) and OpenSimplex2S, 2D slices of 3D in the classic lattice orientation, look decent but are less ideal for X/Y planes being the primary focus.
* This Updated OpenSimplex render appears to show less directional bias than original OpenSimplex.
```cmake
# Consumer project CMakeLists.txt
cmake_minimum_required(VERSION 3.19)
project(consumer LANGUAGES C)

### 4D Noise (ImproveXY_ImproveZW Orientation)
add_subdirectory(third_party/OpenSimplex2)

![Renders 4D ImproveXY_ImproveZW](https://user-images.githubusercontent.com/8829856/149676999-14dc7dfc-a94c-4a8a-b654-00e25f33eb68.png)
add_executable(consumer main.c)

* OpenSimplex2S 4D has higher apparent contrast than original OpenSimplex.
* OpenSimplex2(F) 4D has a very dotty appearance. Fine for fBm, but may pair best with extra steps if used for ridged noise.
# OpenSimplex2Interface is an INTERFACE target: it links the C
# implementation (OpenSimplex2F.c), exposes the repository root as a
# public include directory and links the C math library (-lm).
target_link_libraries(consumer PRIVATE OpenSimplex2Interface)
```

### 4D Noise (ImproveXYZ Orientation)
### Manual build

![Renders 4D ImproveXYZ](https://user-images.githubusercontent.com/8829856/149677002-542aefc5-3e60-46d2-ac4a-6d947c0b94a7.png)
Compile the source file into your project with your C compiler, for example:

* 2D slices look fine, but this rotation is most intended for texturing 3D objects with an additional time variable.
```
cc -Wall -Wextra --pedantic -O3 -c OpenSimplex2F.c -lm
```

### 4D Noise (Fallback Orientation)
Or use the bundled Makefile:

![Renders 4D Fallback](https://user-images.githubusercontent.com/8829856/149677011-267ab94c-3f3b-47bf-85a2-7b00befa95d6.png)
```
make
```

* OpenSimplex2(F) has the most noticeable diagonal artifacts, followed by Old OpenSimplex.
The Makefile also builds the `test_OpenSimplex2F` binary (test source in
`tests/test_OpenSimplex2F.c`), which writes 2D/3D/4D noise images
(requires libpng).

### 4D Noise (Torus Mapping)
### Tests

![Renders 4D Torus](https://user-images.githubusercontent.com/8829856/149677013-c0593b51-b757-41ed-9ece-1bf2f88feee7.png)
To build the tests, keep the `OPENSIMPLEX2_TESTS` option enabled (default
`ON`) and run the `test` target — it builds the `OpenSimplex2tests`
executable from the `tests/` subdirectory and runs it (the targets are
registered with the `addTests()` function of the QuasarApp CMake module):

* Seamless tileable 2D noise from 4D, mapped using noise4(r sin x, r cos x, r sin y, r cos y)
```
cmake -B build
cmake --build build
cmake --build build --target test
```

## Public Domain Dedication
## License

This is free and unencumbered software. The majority of files are released under CC0. Where marked, files in certain directories fall under UNLICENSE instead, as they were based off of UNLICENSE code other than mine (e.g. Pull Requests, legacy OpenSimplex with DigitalShadow's lookup tables). To the best of my non-lawyer knowledge, no patent claims cover anything implemented here (though also nothing here is legal advice). Please use this software to make cool things, rather than to make patents! Enjoy.
This project is provided under the license defined in the
[LICENSE](LICENSE) file.
Loading