lygia 1.1.2 → 1.3.0

package/CONTRIBUTE.md

@@ -0,0 +1,21 @@
+# Contributing to LYIGA
+
+LYGIA is a project that aims to provide a unified API for writing shaders in different shading languages, with carefully tailored code, optimized for each language. It is a community-driven project and we welcome contributions from everyone.
+
+At the moment we are figuring the best way to organize the project and the best practices to follow. If you have any suggestions, please open an issue.
+
+As a general guideline, we are following these rules:
+
+* Everything goes through PRs. No standalone commits.
+* PRs need to be peer-reviewed by at least one language lead
+* PRs that change existing functions need to maintain language parity.
+
+## Who are the language leads?
+
+* GLSL: @patriciogonzalezvivo
+* HLSL: Shadi El Hajj (@shadielhajj)
+* WGSL: Stevan Dedovic (@sdedovic) 
+* METAL: Anton Marini (@vade)
+* CUDA: (help wanted)
+* TSL: (help wanted)
+* OSL: (help wanted)

package/DESIGN.md

@@ -0,0 +1,137 @@
+
+## Design Guidelines
+        
+* **Granularity**. One function per file. The file and the function share the same name, namely: `myFunc.glsl` contains `myFunct()`. There are some files that just include a collection of files inside a folder with the same name. For example:
+
+```
+    color/blend.glsl
+    // which includes
+    color/blend/*.glsl
+
+```
+
+* **Multi-language**. Right now, most of the code is GLSL (`*.glsl`) and HLSL (`*.hlsl`), but we are slowly extending to WGSL (`*.wgsl`), CUDA (`*.cuh`) and Metal (`*.msl`).
+
+```
+    math/mirror.glsl
+    math/mirror.hlsl
+    math/mirror.wgsl
+    math/mirror.msl
+    math/mirror.cuh
+```
+
+* **Self documented**. Each file contains a structured comment (in YAML) at the top of the file. This one contains the name of the original author, description, use, `#define` options, and any implementation-specific notes.
+
+```glsl
+
+    /*
+    contributors: <FULL NAME>
+    description: [DESCRIPTION + URL]
+    use: <vec2> myFunc(<vec2> st, <float> x [, <float> y])
+    notes:
+        - The option MYFUNC_TYPE is not supported on WGSL.
+    options:
+        - MYFUNC_TYPE
+        - MYFUNC_SAMPLER_FNC()
+    */
+
+```
+
+* **Prevent name collisions** by using the following pattern where `FNC_` is followed with the function name:
+
+```glsl
+
+    #ifndef FNC_MYFUNC
+    #define FNC_MYFUNC
+
+    float myFunc(float in) {
+        return in;
+    }
+
+    #endif
+
+```
+
+* **Templating capabilities through `#defines`**. Probably the most frequent use is templating the sampling function for reusability. The `#define` options start with the name of the function, in this example `MYFUNC_`. They are added as `options:` in the header.
+ 
+```glsl
+
+    #ifndef MYFUNC_TYPE
+    #define MYFUNC_TYPE vec4
+    #endif
+
+    #ifndef MYFUNC_SAMPLER_FNC
+    #define MYFUNC_SAMPLER_FNC(TEX, UV) texture2D(TEX, UV)
+    #endif
+
+    #ifndef FNC_MYFUNC
+    #define FNC_MYFUNC
+    MYFUNC_TYPE myFunc(SAMPLER_TYPE tex, vec2 st) {
+        return MYFUNC_SAMPLER_FNC(tex, st);
+    }
+    #endif
+
+```
+
+* **Argument order**. Optional elements are at the end. When possible sort them according their memory footprint (except textures that remain at the top). Ex.: `SAMPLER_TYPE, mat4, mat3, mat2, vec4, vec3, vec2, float, ivec4, ivec3, ivec2, int, bool`
+
+```glsl
+
+    /*
+    ...
+    use: myFunc(<vec2> st, <vec2|float> x[, <float> y])
+    */
+
+    #ifndef FNC_MYFUNC
+    #define FNC_MYFUNC
+    vec2 myFunc(vec2 st, vec2 x) {
+        return st * x;
+    }
+
+    vec2 myFunc(vec2 st, float x) {
+        return st * x;
+    }
+
+    vec2 myFunc(vec2 st, float x, float y) {
+        return st * vec2(x, y);
+    }
+    #endif
+
+```
+
+### WGSL Specifics
+
+WGSL as a language has some fundamental differences from GLSL, HLSL and METAL. Here are some guidelines to help with the transition:
+
+* **WGSL Function Renaming**. WGSL [does not support function overloading](https://github.com/gpuweb/gpuweb/issues/876) and as such function names must be unique and should reflect the size of parameter, return types. See documented examples below.
+
+```wgsl
+    // When the parameter types and return type is consistent and scalar, no suffix is needed.
+    fn random(p: f32) -> f32 { ... }
+
+    /*
+    When only the return type is consistent and scalar, the function name is suffixed based on the size of the parameter types, i.e.
+      - vec2<T> -> 2
+      - vec3<T> -> 3
+      - vec4<T> -> 4
+    */
+    fn random2(p: vec2f) -> f32 { ... }
+    fn random3(p: vec3f) -> f32 { ... }
+    fn random3(p: vec4f) -> f32 { ... }
+
+    /* 
+    When both parameters and return types are inconsistent, function name has two suffixes:
+      - first for return type size
+      - second for parameter type size
+    */
+    fn random21(p: f32) -> vec2f { ... }
+    fn random22(p: vec2f) -> vec2f { ... }
+    fn random23(p: vec3f) -> vec2f { ... }
+    fn random31(p: f32) -> vec3f { ... }
+    fn random32(p: vec2f) -> vec3f { ... }
+    fn random33(p_: vec3f) -> vec3f { ... }
+    fn random41(p: f32) -> vec4f { ... }
+    fn random42(p: vec2f) -> vec4f { ... }
+    fn random43(p: vec3f) -> vec4f { ... }
+    fn random44(p: vec4f) -> vec4f { ... }
+```

package/EXAMPLES.md

@@ -0,0 +1,23 @@
+### Integrations examples
+
+Learn more about LYGIA and how to use it from these **examples**:
+
+* [2D examples for Processing (GLSL)](https://github.com/patriciogonzalezvivo/lygia_p5_examples)
+* [2D/3D examples for P5.js (GLSL)](https://editor.p5js.org/patriciogonzalezvivo/sketches)
+* [2D examples for Three.js + React (GLSL)](https://codesandbox.io/s/lygia-react-starter-fftx6p) by [Eduard Fossas](https://eduardfossas.vercel.app/)
+* [2D examples for Three.js (GLSL)](https://github.com/patriciogonzalezvivo/lygia_threejs_examples)
+* [3D examples for Three.js (GLSL)](https://github.com/guidoschmidt/lygia_threejs_examples) by [Guido Schmidt](https://guidoschmidt.cc/)
+* [2D examples for OpenFrameworks (GLSL)](https://github.com/patriciogonzalezvivo/lygia_of_examples) 
+* [2D/3D examples for Unity3D (HLSL)](https://github.com/patriciogonzalezvivo/lygia_unity_examples)
+* [Examples for Unreal Engine (HLSL)](https://github.com/franklzt/lygia_unreal_engine_examples)
+* [Examples for Touch Designer (GLSL)](https://derivative.ca/community-post/asset/lygia-touchdesginer/66804) (dynamic resolver) by [Leith Ben Abdessalem](https://leithba.com)
+* [Examples for Touch Designer (GLSL)](https://github.com/vectorsize/lygia-td) (static resolver) by [Victor Saz](https://github.com/vectorsize)
+* [2D examples on Observable Notebook (GLSL)](https://observablehq.com/@radames/hello-lygia-shader-library) by [Radames Ajna](https://twitter.com/radamar)
+* [Figma's noise&texture plugin](https://www.figma.com/community/plugin/1138854718618193875) by [Rogie King](https://twitter.com/rogie). You will need to go to the "Custom" tab on the plugin to edit shaders and load LYGIA modules  
+* [3D example on Irmf](https://github.com/irmf/irmf-examples/tree/master/examples/028-lygia) by [Glenn Lewis](https://github.com/gmlewis)
+* [2D/3D examples on GlslViewer (GLSL)](https://github.com/patriciogonzalezvivo/lygia_examples)
+* [2D examples on Ossia](https://github.com/ossia/score-examples) by [Jean-Michaël Celerier](https://jcelerier.name/)
+* [Ogl integration](https://github.com/kujohn/lygia_ogl_examples) by [John Ku](https://github.com/kujohn)
+* [2D templates for Ogl(TS) and Three.js(JS/TS)](https://github.com/cdaein/create-ssam) by [Daeinc](https://paperdove.com)
+
+For more information, guidance, or feedback about using LYGIA, join [#Lygia channel on shader.zone discord](https://shader.zone/).

package/README.md

@@ -2,35 +2,17 @@
 
 # LYGIA Shader Library 
 
-Tired of searching, porting and/or reimplementing the same functions over and over? LYGIA is a shader library of reusable functions that can be included easily into your projects. LYGIA is very granular and designed for reusability, performance, and flexibility. LYGIA can easily be added to any project or framework.
-
-[![](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub)](https://github.com/sponsors/patriciogonzalezvivo)
-
-<p style="text-align: center;" >
-    <a href="https://github.com/patriciogonzalezvivo/lygia_unity_examples"><img src="https://lygia.xyz/imgs/unity.png" alt="uUnity" width="64" /></a>
-    <a href="https://github.com/guidoschmidt/lygia_threejs_examples"><img src="https://lygia.xyz/imgs/threejs.png" alt="threejs" width="64" /></a>
-    <a href="https://github.com/patriciogonzalezvivo/lygia_p5_examples"><img src="https://lygia.xyz/imgs/p5.png" alt="p5" width="64" /></a>
-    <a href="https://editor.p5js.org/patriciogonzalezvivo/sketches"><img src="https://lygia.xyz/imgs/p5js.png" alt="p5js" width="64" /></a>
-    <a href="https://github.com/patriciogonzalezvivo/lygia_of_examples"><img src="https://lygia.xyz/imgs/of.png" alt="openFrameworks" width="64" /></a>
-    <a href="https://github.com/vectorsize/lygia-td"><img title="static-resolver by vectorsize" src="https://lygia.xyz/imgs/td.png" alt="touchDesigner" width="64" /></a>
-    <a href="https://github.com/patriciogonzalezvivo/lygia_examples"><img src="https://lygia.xyz/imgs/glslViewer.png" alt="glslViewer" width="64" /></a>
-    <a href="https://observablehq.com/@radames/hello-lygia-shader-library"><img src="https://lygia.xyz/imgs/ob.png" alt="ob" width="64" /></a>
-    <a href="https://codesandbox.io/s/lygia-react-starter-fftx6p"><img src="https://lygia.xyz/imgs/r3f.png" alt="r3rf" width="64" /></a>
-    <a href="https://www.figma.com/community/plugin/1138854718618193875"><img src="https://lygia.xyz/imgs/figma.png" alt="Figma" width="64" /></a>
-    <a href="https://github.com/irmf/irmf-examples/tree/master/examples/028-lygia"><img src="https://lygia.xyz/imgs/irmf.png" alt="irmf" width="64" /></a>
-    <a href="https://github.com/ossia/score-examples"><img src="https://lygia.xyz/imgs/ossia.png" alt="Ossia" width="64" /></a>
-    <a href="https://www.npmjs.com/package/resolve-lygia"><img src="https://lygia.xyz/imgs/npm.png" alt="npm" width="64" /></a>
-
-</p>
+LYGIA is the biggest shader library. Battle proof, cross platform and multi-language. Is made of reusable functions that will let you prototype, port and ship projects in just few minutes. It's very granular, flexible and efficient. Support multiple shading languages and can easily be added to virtually any project. There are already integrations for almost all mayor enviroments, engines and frameworks. 
 
+Best of all, LYGIA grows and improves every day thanks to the support of the community. Become a [Contributor](https://github.com/patriciogonzalezvivo/lygia) or a [![](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub)](https://github.com/sponsors/patriciogonzalezvivo)
 
 ## How to use it?
 
-In your shader `#include` the functions you need:
+In your shader just `#include` the functions you need and then use them:
 
 <div class="codeAndCanvas" data="example.frag">
 
-	#ifdef GL_ES
+    #ifdef GL_ES
     precision mediump float;
     #endif
 
@@ -55,10 +37,54 @@ In your shader `#include` the functions you need:
     
 </div>
 
+If you just need to resolve the dependencies of a shader file you got, the fastest way would be to drag&drop your shader file in the box below. We can resolve the dependencies for you.
+
+<div class="container">
+    <div class="file-drop-area">
+    <span class="file-msg">Drop your shader file <a href="https://lygia.xyz/">here</a></span>
+    </div>
+</div>
+
+LYGIA have been integrated into the following Engines, Frameworks, Creative Tools and online editors:
+
+<p style="text-align: center;" >
+    <a href="https://github.com/patriciogonzalezvivo/lygia_unity_examples"><img src="https://lygia.xyz/imgs/unity.png" alt="unity" title="unity" width="64" /></a>
+    <a href="https://github.com/franklzt/lygia_unreal_engine_examples"><img src="https://lygia.xyz/imgs/unreal.png" alt="unreal" title="unreal" width="64" /></a>
+    <a href="https://www.curseforge.com/minecraft/search?page=1&pageSize=20&sortType=1&search=LYGIA%20Shader%20Library"><img src="https://lygia.xyz/imgs/minecraft.png" alt="minecraft" title="minecraft" width="64" /></a>
+    <a href="https://github.com/patriciogonzalezvivo/lygia_examples"><img src="https://lygia.xyz/imgs/glslViewer.png" alt="glslViewer" title="glslViewer" width="64" /></a>
+    <a href="https://github.com/irmf/irmf-examples/tree/master/examples/028-lygia"><img src="https://lygia.xyz/imgs/irmf.png" alt="irmf" title="irmf" width="64" /></a>
+</p>
+
+<p style="text-align: center;" >
+    <a href="https://github.com/guidoschmidt/lygia_threejs_examples"><img src="https://lygia.xyz/imgs/threejs.png" alt="threejs" title="threejs" width="64" /></a>
+    <a href="https://github.com/kujohn/lygia_ogl_examples"><img src="https://lygia.xyz/imgs/ogl.png" alt="ogl" title="ogl" width="64" /></a>
+    <a href="https://www.npmjs.com/package/lygia"><img src="https://lygia.xyz/imgs/npm.png" alt="npm" title="npm" width="64" /></a>
+    <a href="https://codesandbox.io/s/lygia-react-starter-fftx6p"><img src="https://lygia.xyz/imgs/r3f.png" alt="r3rf" title="r3rf" width="64" /></a>
+</p>
+
+<p style="text-align: center;" >
+    <a href="https://github.com/patriciogonzalezvivo/lygia_p5_examples"><img src="https://lygia.xyz/imgs/p5.png" alt="p5" title="processing" width="64" /></a>
+    <a href="https://editor.p5js.org/patriciogonzalezvivo/sketches"><img src="https://lygia.xyz/imgs/p5js.png" alt="p5js" title="p5js" width="64" /></a>
+    <a href="https://github.com/patriciogonzalezvivo/lygia_of_examples"><img src="https://lygia.xyz/imgs/of.png" alt="openFrameworks" tittle="openframeworks" width="64" /></a>
+    <a href="https://github.com/vectorsize/lygia-td"><img title="static-resolver by vectorsize" src="https://lygia.xyz/imgs/td.png" alt="touchDesigner" title="touchDesigner" width="64" /></a>
+    <a href="https://github.com/patriciogonzalezvivo/comfyui_glslnodes"><img src="https://lygia.xyz/imgs/comfy.png" alt="comfyui" title="comfyUI" width="64" /></a>
+    <a href="https://github.com/ossia/score-examples"><img src="https://lygia.xyz/imgs/ossia.png" alt="ossia" title="ossia" width="64" /></a>
+</p>
+
+<p style="text-align: center;" >
+    <a href="https://www.figma.com/community/plugin/1138854718618193875"><img src="https://lygia.xyz/imgs/figma.png" alt="figma" title="figma" width="64" /></a>
+    <a href="https://observablehq.com/@radames/hello-lygia-shader-library"><img src="https://lygia.xyz/imgs/ob.png" alt="observable" title="observable" width="64" /></a>
+    <a href="https://www.productioncrate.com/laforge/"><img src="https://lygia.xyz/imgs/laforge.png" alt="laforge" title="laforge" width="64" /></a>
+    <a href="https://synesthesia.live/"><img src="https://lygia.xyz/imgs/synesthesia.png" alt="synesthesia" title="synesthesia" width="64" /></a>
+    <a href="https://glsl.app/"><img src="https://glsl.app/icon-256.png" alt="glslApp" title="glslApp" width="64"/></a>
+    <a href="https://dev.shader.app/"><img src="https://dev.shaders.app/apple-touch-icon.png" alt="shaderApp" title="shaderApp" width="64"/></a>
+</p>
+
+If you are working on a project and want to use LYGIA, you have two options: cloning a **local** version that then you can bundle into your project; or using the **server** ( https://lygia.xyz ) to resolve the dependencies online. How each one works?
 
 ### LYGIA Locally
 
-If you are working **locally** in an environment that can resolve `#include` dependencies, just clone LYGIA into your project relative to the shader you are loading:
+If you want to work **locally**, you must ensure that your environment can resolve `#include` dependencies. You can find some examples in [here specially for GLSL](https://github.com/patriciogonzalezvivo/lygia/blob/main/README_GLSL.md). Then you just need to clone LYGIA into your project relative to the shader you are loading:
 
 ```bash
     git clone https://github.com/patriciogonzalezvivo/lygia.git
@@ -70,9 +96,26 @@ or as a submodule:
     git submodule add https://github.com/patriciogonzalezvivo/lygia.git
 ```
 
-### LYGIA on the cloud
+Alternatively you may clone LYGIA without the git history and reduce the project size (9MB+) with the following command:
+
+```bash
+    npx degit https://github.com/patriciogonzalezvivo/lygia.git lygia
+```
+
+If you are concerned about the size of the library you might also be interested on pruning the library to only the language you are using. You can do that by using the `prune.py` script. For example:
+
+```bash
+    python prune.py --all --keep glsl
+```
+
+Alternatively, if your are working on a `npm` project, there is a [npm bundle](https://www.npmjs.com/package/lygia) you could use.
+
+If you are working on web project you may want to resolve the dependencies using a bundler like [vite glsl plugin (local bundle)](https://github.com/UstymUkhman/vite-plugin-glsl), [esbuild glsl plugin (local bundle)](https://github.com/ricardomatias/esbuild-plugin-glsl-include) or [webpack glsl plugin (local bundle)](https://github.com/grieve/webpack-glsl-loader).
 
-If you are working on a **cloud platform** you probably want to resolve the dependencies without needing to install anything. Just add a link to `https://lygia.xyz/resolve.js` (JS) or `https://lygia.xyz/resolve.esm.js` (ES6 module): 
+
+### LYGIA server
+
+If you are working on a **cloud platform** (like [CodePen](https://codepen.io/) or [Observable](https://observablehq.com/@radames/hello-lygia-shader-library) ) you probably want to resolve the dependencies without needing to install anything. For that just add a link to `https://lygia.xyz/resolve.js` (JS) or `https://lygia.xyz/resolve.esm.js` (ES6 module): 
 
 ```html
     <!-- as a JavaScript source -->
@@ -105,29 +148,14 @@ To then resolve the dependencies by passing a `string` or `strings[]` to `resolv
     shdr = createShader(vertSource, fragSource);
 ```
 
-### Integrations examples
-
-Learn more about LYGIA and how to use it from these **examples**:
-
-* [2D examples for Processing (GLSL)](https://github.com/patriciogonzalezvivo/lygia_p5_examples)
-* [2D/3D examples for P5.js (GLSL)](https://editor.p5js.org/patriciogonzalezvivo/sketches)
-* [2D examples for Three.js + React (GLSL)](https://codesandbox.io/s/lygia-react-starter-fftx6p) by [Eduard Fossas](https://eduardfossas.vercel.app/)
-* [2D examples for Three.js (GLSL)](https://github.com/patriciogonzalezvivo/lygia_threejs_examples)
-* [3D examples for Three.js (GLSL)](https://github.com/guidoschmidt/lygia_threejs_examples) by [Guido Schmidt](https://guidoschmidt.cc/)
-* [2D examples for OpenFrameworks (GLSL)](https://github.com/patriciogonzalezvivo/lygia_of_examples) 
-* [2D/3D examples for Unity3D (HLSL)](https://github.com/patriciogonzalezvivo/lygia_unity_examples)
-* [2D examples for Touch Designer (GLSL)](https://derivative.ca/community-post/asset/lygia-touchdesginer/66804) (dynamic resolver) by [Leith Ben Abdessalem](https://leithba.com)
-* [2D examples for Touch Designer (GLSL)](https://github.com/vectorsize/lygia-td) (static resolver) by [Victor Saz](https://github.com/vectorsize)
-* [2D examples on Observable Notebook (GLSL)](https://observablehq.com/@radames/hello-lygia-shader-library) by [Radames Ajna](https://twitter.com/radamar)
-* [Figma's noise&texture plugin](https://www.figma.com/community/plugin/1138854718618193875) by [Rogie King](https://twitter.com/rogie). You will need to go to the "Custom" tab on the plugin to edit shaders and load LYGIA modules  
-* [3D example on Irmf](https://github.com/irmf/irmf-examples/tree/master/examples/028-lygia) by [Glenn Lewis](https://github.com/gmlewis)
-* [2D/3D examples on GlslViewer (GLSL)](https://github.com/patriciogonzalezvivo/lygia_examples)
-* [2D examples on Ossia by Jean-Michaël Celerier](https://github.com/ossia/score-examples)
-
-For more information, guidance, or feedback about using LYGIA, join [#Lygia channel on shader.zone discord](https://shader.zone/).
+This function can also resolve dependencies to previous versions of LYGIA by using this pattern `lygia/vX.X/...` or `lygia/vX.X.X/...` on you dependency paths. For example:
 
+```glsl
+#include "lygia/v1.0/math/decimation.glsl"
+#include "lygia/v1.2.1/math/decimation.glsl"
+```
 
-### How is it organized?
+### How is LYGIA organized?
 
 The functions are divided into different categories:
 
@@ -141,13 +169,14 @@ The functions are divided into different categories:
 * [`sample/`](https://lygia.xyz/sample): sample operations
 * [`filter/`](https://lygia.xyz/filter): typical filter operations: different kind of blurs, mean and median filters.
 * [`distort/`](https://lygia.xyz/distort): distort sampling operations
-* [`simulate/`](https://lygia.xyz/simulate): simulate sampling operations
 * [`lighting/`](https://lygia.xyz/lighting): different lighting models and functions for foward/deferred/raymarching rendering
 * [`geometry/`](https://lygia.xyz/geometry): operation related to geometries: intersections and AABB accelerating structures.
 * [`morphological/`](https://lygia.xyz/morphological): morphological filters: dilation, erosion, alpha and poisson fill.
 
-### Flexible how?
 
+### How is it [designed](https://github.com/patriciogonzalezvivo/lygia/blob/main/DESIGN.md)?
+
+LYGIA is designed to be very granular (each file holds one function), multilanguage (each language have it's onw file extension) and flexible. Flexible how?
 There are some functions whose behavior can be changed using the `#defines` keyword before including it. For example, [gaussian blurs](filter/gaussianBlur.glsl) are usually are done in two passes. By default, these are performed on their 1D version, but if you are interested in using a 2D kernel, all in the same pass, you will need to add the `GAUSSIANBLUR_2D` keyword this way:
 
 ```glsl
@@ -165,159 +194,48 @@ There are some functions whose behavior can be changed using the `#defines` keyw
 
 ```
 
+In the same way you can change the sampling function that the gaussian uses. Ex:
 
-## Design Principles
-
-1. It relies on `#include "path/to/file.*lsl"` which is defined by Khronos GLSL standard and requires a typical C-like pre-compiler MACRO which is easy to implement with just basic string operations to resolve dependencies. 
-
-Here you can find some implementations on different languages:
-
-  - C#:
-  
-    . [GLSLIncludes](https://github.com/seb776/GLSLIncludes) a small utility to add the include feature to glsl by [z0rg](https://github.com/seb776).
-
-  - C++:
-
-    . [VERA's routines](https://github.com/patriciogonzalezvivo/vera/blob/main/src/ops/fs.cpp#L110-L171) for resolving GLSL dependencies.
-
-  - Python:
-
-    . [Small and simple routing to resolve includes](https://gist.github.com/patriciogonzalezvivo/9a50569c2ef9b08058706443a39d838e)
-
-  - JavaScript: 
-  
-    . [vanilla JS (online resolver)](https://lygia.xyz/resolve.js) This small file brings `resolveLygia()` which takes a `string` or `string[]` and parses it, solving all the `#include` dependencies into a single `string` you can load on your shaders.
-  
-    . [npm module (online resolver)](https://www.npmjs.com/package/resolve-lygia) by Eduardo Fossas; [vite glsl plugin (local bundle)](https://github.com/UstymUkhman/vite-plugin-glsl) by Ustym Ukhman. Imports `.glsl` local dependencies, or load inline shaders through vite.
-  
-    . [esbuild glsl plugin (local bundle)](https://github.com/ricardomatias/esbuild-plugin-glsl-include) by Ricardo Matias. Imports local `.glsl` dependencies through esbuild.
-
-    . [webpack glsl plugin (local bundle)](https://github.com/grieve/webpack-glsl-loader) by Ryan Grieve that imports local `.glsl` dependencies through webpack.
-        
-* It's **very granular**. One function per file. The file and the function share the same name, namely: `myFunc.glsl` contains `myFunct()`. There are some files that just include a collection of files inside a folder with the same name. For example:
-
-```
-    color/blend.glsl
-    // which includes
-    color/blend/*.glsl
-
-```
-
-* It's **multi language**. Right now most of is GLSL (`*.glsl`) and HLSL (`*.hlsl`), but we are slowly extending to WGSL (`*.wgsl`), CUDA (`*.cuh`) and Metal (`*.msl`).
-
-```
-    math/mirror.glsl
-    math/mirror.hlsl
-    math/mirror.wgsl
-    math/mirror.msl
-    math/mirror.cuh
-```
-
-* **Self documented**. Each file contains a structured comment (in YAML) at the top of the file. This one contains the name of the original author, description, use, and `#define` options
-
-```glsl
-
-    /*
-    original_author: <FULL NAME>
-    description: [DESCRIPTION + URL]
-    use: <vec2> myFunc(<vec2> st, <float> x [, <float> y])
-    options:
-        - MYFUNC_TYPE
-        - MYFUNC_SAMPLER_FNC()
-    */
-
-```
-
-* Prevents **name collisions** by using the following pattern where `FNC_` is followed with the function name:
-
-```glsl
-
-    #ifndef FNC_MYFUNC
-    #define FNC_MYFUNC
-
-    float myFunc(float in) {
-        return in;
-    }
-
-    #endif
-
-```
-
-* **Templating capabilities through `#defines`**. Probably the most frequent use is templating the sampling function for reusability. The `#define` options start with the name of the function, in this example `MYFUNC_`. They are added as `options:` in the header.
- 
 ```glsl
-
-    #ifndef MYFUNC_TYPE
-    #define MYFUNC_TYPE vec4
-    #endif
-
-    #ifndef MYFUNC_SAMPLER_FNC
-    #define MYFUNC_SAMPLER_FNC(TEX, UV) texture2D(TEX, UV)
-    #endif
-
-    #ifndef FNC_MYFUNC
-    #define FNC_MYFUNC
-    MYFUNC_TYPE myFunc(sampler2D tex, vec2 st) {
-        return MYFUNC_SAMPLER_FNC(tex, st);
-    }
-    #endif
-
+// from
+#define GAUSSIANBLUR_SAMPLER_FNC(TEX, UV) texture2D(TEX, UV)
+// to 
+#include "lygia/sample/clamp2edges.glsl"
+#define GAUSSIANBLUR_SAMPLER_FNC(TEX, UV) sampleClamp2edge(TEX, UV)
 ```
 
-* **Function Overloading**. Arguments are arranged in such a way that optional elements are at the end. When possible sort them according their memory size (except textures that remain at the top). Ex.: `sampler2D, mat4, mat3, mat2, vec4, vec3, vec2, float, ivec4, ivec3, ivec2, int, bool`
-
-```glsl
-
-    /*
-    ...
-    use: myFunc(<vec2> st, <vec2|float> x[, <float> y])
-    */
-
-    #ifndef FNC_MYFUNC
-    #define FNC_MYFUNC
-    vec2 myFunc(vec2 st, vec2 x) {
-        return st * x;
-    }
-
-    vec2 myFunc(vec2 st, float x) {
-        return st * x;
-    }
-
-    vec2 myFunc(vec2 st, float x, float y) {
-        return st * vec2(x, y);
-    }
-    #endif
-
-```
+Learn more about [LYGIAS design principles in the DESIGN.md file](https://github.com/patriciogonzalezvivo/lygia/blob/main/DESIGN.md).
 
 ## Contributions
 
-LYGIA has a long way to go. Your support will be appreciated and rewarded! All contributors are automatically added to the [commercial license](https://lygia.xyz/license). This support can take multiple forms:
+LYGIA has a long way to go and welcomes all kinds of contributions. You can help by:
 
-* fixing bugs!
-* expanding the cross-compatibility between languages GLSL/HLSL/MSL/WGSL/CUDA
-* contributing new functions
-* adding new examples and integrations for new environments like: [GoDot](https://godotengine.org/), [ISF](https://isf.video/), [MaxMSP](https://cycling74.com/products/max), etc.
-* through [sponsorships](https://github.com/sponsors/patriciogonzalezvivo)
+* **Bug fixing**
+* **Translation**, keeping parity between languages (GLSL, HLSL, MSL, WGSL, TSL, CUDA, OSL, etc) is a big part of the challenge. Not all language are the same and we want to make sure make sure each function is optimized and carefully crafted for each enviroment. This means, the more eyes looking at this, the better. Please make sure to read and understand the [Design Principles](https://github.com/patriciogonzalezvivo/lygia/blob/main/DESIGN.md) before starting.
+* **New functions or improving the current implementations**. Please take a look to the [Contributing Guidelines](https://github.com/patriciogonzalezvivo/lygia/blob/main/CONTRIBUTING.md) before starting.
+* **Documentation**. Each function has a header with some information describing the function. Make sure to fill this information when adding a new function.
+* Adding new **examples** and integrations for new environments like: [Godot](https://godotengine.org/), [ISF](https://isf.video/), [MaxMSP](https://cycling74.com/products/max), etc.
+* **Financial** [sponsorships](https://github.com/sponsors/patriciogonzalezvivo). Right now, the money that flows in is invested on the server and infraestructure. Long term plan will be to be able to pay lead contributors and mantainers.
 
+Collaborators and sponsors are automatically added to the [commercial license](https://lygia.xyz/license). Making a PR or subscribing to the github sponsors program is the shortest path to get access to the commercial license. It's all automated, not red taping. LYGIA belongs to those that takes care of it.
 
 ## License 
 
-LYGIA is dual-licensed under the [Prosperity License](https://prosperitylicense.com/versions/3.0.0) and the [Patron License](https://lygia.xyz/license) for [sponsors](https://github.com/sponsors/patriciogonzalezvivo) and [contributors](https://github.com/patriciogonzalezvivo/lygia/graphs/contributors).
+LYGIA belongs to those that support it. For that it uses a dual-licensed under the [Prosperity License](https://prosperitylicense.com/versions/3.0.0) and the [Patron License](https://lygia.xyz/license) for [sponsors](https://github.com/sponsors/patriciogonzalezvivo) and [contributors](https://github.com/patriciogonzalezvivo/lygia/graphs/contributors).
 
-[Sponsors](https://github.com/sponsors/patriciogonzalezvivo) and [contributors](https://github.com/patriciogonzalezvivo/lygia/graphs/contributors) are automatically added to the [Patron License](https://lygia.xyz/license) and they can ignore any non-commercial rule of the [Prosperity License](https://prosperitylicense.com/versions/3.0.0) software (please take a look at the exceptions).
+[Sponsors](https://github.com/sponsors/patriciogonzalezvivo) and [contributors](https://github.com/patriciogonzalezvivo/lygia/graphs/contributors) are automatically added to the [Patron License](https://lygia.xyz/license) and they can ignore any non-commercial rule of the [Prosperity License](https://prosperitylicense.com/versions/3.0.0) software.
 
 It's also possible to get a permanent commercial license hooked to a single and specific version of LYGIA.
 
-**Exceptions**:
-
-* `color/mixBox.glsl` and `color/mixBox.hlsl` are copyrighted by Secret Weapons with their own non-commercial license. These functions also require a LUT texture which is provided for research and evaluation purposes, if you wish to obtain it together with a commercial license, please contact them at [mixbox@scrtwpns.com](mailto:mixbox@scrtwpns.com).
+If you have doubts please reaching out to patriciogonzalezvivo at gmail dot com
 
 ## Credits
 
-Created and mantained by [Patricio Gonzalez Vivo](https://patriciogonzalezvivo.com/)( <a rel="me" href="https://merveilles.town/@patricio">Mastodon</a> | [Twitter](https://twitter.com/patriciogv) | [Instagram](https://www.instagram.com/patriciogonzalezvivo/) | [GitHub](https://github.com/sponsors/patriciogonzalezvivo) ) and every direct or indirect [contributors](https://github.com/patriciogonzalezvivo/lygia/graphs/contributors) to the GitHub. This library has been built over years, and in many cases on top of the work of brilliant and generous people like: [Inigo Quiles](https://www.iquilezles.org/), [Morgan McGuire](https://casual-effects.com/), [Alan Wolfe](https://blog.demofox.org/), [Hugh Kennedy](https://github.com/hughsk), [Matt DesLauriers](https://www.mattdesl.com/), and many others.
+Created and mantained by [Patricio Gonzalez Vivo](https://patriciogonzalezvivo.com/)( <a rel="me" href="https://merveilles.town/@patricio">Mastodon</a> | [Twitter](https://twitter.com/patriciogv) | [Instagram](https://www.instagram.com/patriciogonzalezvivo/) | [GitHub](https://github.com/sponsors/patriciogonzalezvivo) ) and every direct or indirect [contributors](https://github.com/patriciogonzalezvivo/lygia/graphs/contributors) to the GitHub. 
+
+This library has been built in many cases on top of the work of brilliant and generous people like: [Inigo Quiles](https://www.iquilezles.org/), [Morgan McGuire](https://casual-effects.com/), [Alan Wolfe](https://blog.demofox.org/), [Matt DesLauriers](https://www.mattdesl.com/), [Bjorn Ottosson](https://github.com/bottosson), [Hugh Kennedy](https://github.com/hughsk), and many others.
+
+Also is being constantly mantain, translated and/or extended by generous contributors like: [Shadi El Hajj](https://github.com/shadielhajj), [Kathy](https://github.com/kfahn22), [Bonsak Schiledrop](https://github.com/bonsak), [Amin Shazrin](https://github.com/ammein), [Guido Schmidt](https://github.com/guidoschmidt), and many others.
 
 
-## Get the latest news and releases
 
-Sign up for the news letter below, join [the LYGIA's channel on Discord](https://shader.zone) or follow the [Github repository](https://github.com/patriciogonzalezvivo/lygia)

package/README_GLSL.md

@@ -0,0 +1,27 @@
+LYGIA relies on `#include "path/to/file.glsl"` which is defined by Khronos GLSL standard but it's up to the project developer to implement. Good news is that it's not that hard, it just requires a typical C-like MACRO pre-compiler, which is easy to implement with just basic string operations to resolve dependencies.
+
+Here you can find some examples in different languages:
+
+  - C#:
+  
+    . [GLSLIncludes](https://github.com/seb776/GLSLIncludes) a small utility to add the include feature to glsl by [z0rg](https://github.com/seb776).
+
+  - C++:
+
+    . [VERA's routines](https://github.com/patriciogonzalezvivo/vera/blob/main/src/ops/fs.cpp#L110-L171) for resolving GLSL dependencies.
+
+  - Python:
+
+    . [Small and simple routing to resolve includes](https://gist.github.com/patriciogonzalezvivo/9a50569c2ef9b08058706443a39d838e)
+
+  - JavaScript: 
+  
+    . [vanilla JS (online resolver)](https://lygia.xyz/resolve.js) This small file brings `resolveLygia()` which takes a `string` or `string[]` and parses it, solving all the `#include` dependencies into a single `string` you can load on your shaders. It also has a `resolveLygiaAsync()` version that resolves all the dependencies in parallel. Both support dependencies to previous versions of LYGIA by using this pattern `lygia/vX.X.X/...` on you dependency paths. 
+  
+    . [npm module (online resolver)](https://www.npmjs.com/package/resolve-lygia) by Eduardo Fossas. This is bring the same `resolveLygia()` and `resolveLygiaAsync()` function but as a npm module.
+
+    . [vite glsl plugin (local bundle)](https://github.com/UstymUkhman/vite-plugin-glsl) by Ustym Ukhman. Imports `.glsl` local dependencies, or load inline shaders through vite.
+  
+    . [esbuild glsl plugin (local bundle)](https://github.com/ricardomatias/esbuild-plugin-glsl-include) by Ricardo Matias. Imports local `.glsl` dependencies through esbuild.
+
+    . [webpack glsl plugin (local bundle)](https://github.com/grieve/webpack-glsl-loader) by Ryan Grieve that imports local `.glsl` dependencies through webpack.

package/README_METAL.md

@@ -0,0 +1,56 @@
+# METAL version
+
+Metal support is currently highly experimental and very work in progress.
+
+## Porting Progress
+
+- [ ] Animation
+- [x] Blend
+- [ ] Color 
+  - [x] Blend
+  - [x] Dither (not fully vetted / just spot checked)
+  - [ ] Palette 
+  - [x] Levels
+  - [x] Space
+  - [ ] Tonemap
+- [x] Distort
+- [x] Draw - (not fully vetted / just spot checked)
+- [ ] Filters
+    - [x] Gaussian Blur
+    - [x] Box 2d 
+- [x] Generative (not fully vetted / just spot checked)
+- [ ] Geometry
+- [ ] Lighting 
+- [x] Math - (not fully vetted / just spot checked)
+- [ ] Morphological
+- [ ] Sample
+- [x] Sampler
+- [x] SDF - (not fully vetted / just spot checked)
+- [ ] Space
+
+## Porting Methodology
+
+- dupe `*.glsl` files-> and rename them to  `*.msl`
+- find replace `.glsl` -> `.msl` and ensure you repeat the above for imports
+- find replace `vec2` -> `float2`
+- find replace `vec3` -> `float3`
+- find replace `vec4` -> `float4`
+- find replace `matN` -> `matrix<float, n, n>`
+- find replace `in ` function argument keyword -> `` as metal doesn't have the in function keyword
+- find `inout` and determine which thread local memory keyword should replace it, and make it a reference
+- ensure `const` is only used within functions, `constant` must be used for global scoped constants
+
+## Things to look out for
+
+- Metal does not have the same basic math functions signatures as GLSL. We are adding all the polyfill functions in the  `math/` folder.
+- Texture precision and filtering.
+    - Added `SAMPLER_TYPE` which specifies the texture precisions. Defaults to `texture2d<float>`
+    - This means your texture definition must match the default `float` precision, or you will need to override `SAMPLER_TYPE`
+    - Added `SAMPLER` which specifies the Metal sampler object. Defaults to `sampler( min_filter::linear, mag_filter::linear )`
+    
+## Things not yet done
+
+- `gl_FragCoord` compatibilty. Not sure if there is a nice way to make this work without end users annotating their root Metal shader entry point.
+    - For now, use the function definitions which pass the [[position]] coords from your main shader.
+- `atan` / `atan2` compatibility. Need to see if there is a nice way to override the function signatures to match.
+