# egret - shader note

[TOC]

## filter
在 egret 內要使用自定義的 shader, 要透過 [egret.CustomFilter](https://docs.egret.com/engine/docs/api/engine/egret.CustomFilter) 影響物件.

### 限制
- 目標物件需要是 [egret.DisplayObject](https://docs.egret.com/engine/docs/api/engine/egret.DisplayObject) 或其子孫.

### 啟用/關閉
控制 [filters](https://docs.egret.com/engine/docs/api/engine/egret.DisplayObject#filters) 加入/移除 filter 物件.
#### 注意事項
`filters` 不可為空陣列(`[]`), 但可為 `undefined`.

---

## glsl 變數的三種修飾詞
| 名稱 | 用途 | vertex | fragment | egret命名習慣 |
| - | - | - | - | - |
| uniform | 外部傳入、不可在shader內修改 | `r` | `r` | `u{變數名}` |
| attribute | 頂點相關的資訊 | `r`| - | `a{變數名}` |
| varying | vertex -> fragment的變數 |`r` `w` | `r` | `v{變數名}` |

---

## egret shader 基礎參數
|名稱|類型|用途|
|-|-|-|
| aVertexPosition | attribute | 頂點座標(world or local?) |
| aTextureCoord | attribute | 預設貼圖採樣座標 |
| aColor | attribute | 頂點顏色 |
| projectionVector | uniform | 投影向量 |
| uTextureSize | uniform | 貼圖尺寸 |
| uSampler | uniform | 貼圖 |
| uSamplerAlphaMask | uniform | alpha遮罩 |

---

## uniform 參數規格
參考 [EgretWebGLUniform.ts](https://github.com/egret-labs/egret-core/blob/master/src/egret/web/rendering/webgl/EgretWebGLUniform.ts)

### 原始碼片段

// 9e461f04f62161b32f155b751a1acfe89a8af944
private generateSetValue():void {
    let type = this.type;

    switch (type) {
        case WEBGL_UNIFORM_TYPE.FLOAT:
        case WEBGL_UNIFORM_TYPE.SAMPLER_2D:
        case WEBGL_UNIFORM_TYPE.SAMPLER_CUBE:
        case WEBGL_UNIFORM_TYPE.BOOL:
        case WEBGL_UNIFORM_TYPE.INT:
            this.setValue = function(value) {
                let notEqual = this.value !== value;
                this.value = value;
                notEqual && this.upload();
            }
            break;
        case WEBGL_UNIFORM_TYPE.FLOAT_VEC2:
        case WEBGL_UNIFORM_TYPE.BOOL_VEC2:
        case WEBGL_UNIFORM_TYPE.INT_VEC2:
            this.setValue = function(value) {
                let notEqual = this.value[0] !== value.x || this.value[1] !== value.y;
                this.value[0] = value.x;
                this.value[1] = value.y;
                notEqual && this.upload();
            }
            break;
        case WEBGL_UNIFORM_TYPE.FLOAT_VEC3:
        case WEBGL_UNIFORM_TYPE.BOOL_VEC3:
        case WEBGL_UNIFORM_TYPE.INT_VEC3:
            this.setValue = function(value) {
                this.value[0] = value.x;
                this.value[1] = value.y;
                this.value[2] = value.z;
                this.upload();
            }
            break;
        case WEBGL_UNIFORM_TYPE.FLOAT_VEC4:
        case WEBGL_UNIFORM_TYPE.BOOL_VEC4:
        case WEBGL_UNIFORM_TYPE.INT_VEC4:
            this.setValue = function(value) {
                this.value[0] = value.x;
                this.value[1] = value.y;
                this.value[2] = value.z;
                this.value[3] = value.w;
                this.upload();
            }
            break;

        case WEBGL_UNIFORM_TYPE.FLOAT_MAT2:
        case WEBGL_UNIFORM_TYPE.FLOAT_MAT3:
        case WEBGL_UNIFORM_TYPE.FLOAT_MAT4:
            this.setValue = function(value) {
                this.value.set(value);
                this.upload();
            }
            break;
    }
}

### 速查表

#### 純量 Scalars
| glsl格式 | ts格式 |
| - | - |
| float | number |
| bool | boolean |
| int | number |

#### 向量 Vectors
| glsl格式 | ts格式 |
| - | - |
| vec2 | {x: number, y: number} |
| vec3 | {x: number, y: number, z: number} |
| vec4 | {x: number, y: number, z: number, w: number} |
| bvec2 | {x: boolean, y: boolean} |
| bvec3 | {x: boolean, y: boolean, z: boolean} |
| bvec4 | {x: boolean, y: boolean, z: boolean, w: boolean} |
| ivec2 | {x: number, y: number} |
| ivec3 | {x: number, y: number, z: number} |
| ivec4 | {x: number, y: number, z: number, w: number} |

#### 矩陣 Matrix
| glsl格式 | ts格式 |
| - | - |
| mat2 | number[4] |
| mat3 | number[9] |
| mat4 | number[16] |

#### 貼圖 Texture (目前暫不支援)
| glsl格式 | ts格式 |
| - | - |
| sampler2D | ? |
| samplerCube | ? |

---

## ref
- [Egret - 自定义Shader](https://docs.egret.com/engine/docs/render-2d/colorEffects/shader)
- [Data Type (GLSL)
](https://www.khronos.org/opengl/wiki/Data_Type_(GLSL))
- [GLSL type checker, formatter, and minifier online demo](http://evanw.github.io/glslx/)
- [OPENGL ES SHADING LANGUAGE TYPES](https://www.shaderific.com/glsl-types)
- [GLSL 三种变量类型（uniform，attribute和varying）理解](https://www.jianshu.com/p/eed3ebdad4fb)
- [GLSL中的精度限定符](https://juejin.cn/post/6844904015696756743)
- [JavaScript中的颜色空间转换](https://segmentfault.com/a/1190000019700896?utm_source=sf-similar-article)
- [Android OpenGL ES - 反相、曝光、对比度、饱和度、色调滤镜](https://segmentfault.com/a/1190000037668990)
- [OpenGL学习——简单滤镜](https://hello-david.github.io/archives/1294c030.html)
- [GLSL Color Correction Shaders](https://alaingalvan.tumblr.com/post/79864187609/glsl-color-correction-shaders)

###### tags: `egret` `shader` `glsl`