mirror of
https://github.com/visgl/luma.gl.git
synced 2025-12-08 17:36:19 +00:00
125 lines
4.5 KiB
Markdown
125 lines
4.5 KiB
Markdown
# ProgramManager
|
|
|
|
The `ProgramManager` manages the creation and caching of programs. It allows the application to request a program based on a vertex shader, fragment shader and set of defines, modules and code injections. The `ProgramManager` will return the requested program, creating it the first time, and re-using a cached version if it is requested more than once. It also allows for the definition of hook functions and module code injections to be inserted into shaders.
|
|
|
|
|
|
## Usage
|
|
|
|
```js
|
|
const pm = new ProgramManager(gl);
|
|
|
|
const vs = `
|
|
attribute vec4 position;
|
|
|
|
void main() {
|
|
#ifdef MY_DEFINE
|
|
gl_Position = position;
|
|
#else
|
|
gl_Position = position.wzyx;
|
|
#endif
|
|
}
|
|
`;
|
|
|
|
const fs = `
|
|
void main() {
|
|
gl_FragColor = vec4(1.0, 0.0, 0.0, 1.0);
|
|
MY_SHADER_HOOK(gl_FragColor);
|
|
}
|
|
`;
|
|
|
|
pm.addShaderHook('fs:MY_SHADER_HOOK(inout vec4 color)');
|
|
|
|
pm.addModuleInjection(picking, {
|
|
hook: 'fs:#MY_SHADER_HOOK',
|
|
injection: 'color = picking_filterColor(color);',
|
|
order: Number.POSITIVE_INFINITY
|
|
});
|
|
|
|
pm.addDefaultModule(dirlight); // Will be included in all following programs
|
|
|
|
const program1 = pm.get({vs, fs}); // Basic, no defines, only default module
|
|
const program2 = pm.get({vs, fs}); // Cached, same as program 1, use count 2
|
|
const program3 = pm.get({ // New program, with different source based on define
|
|
vs,
|
|
fs,
|
|
defines: {
|
|
MY_DEFINE: true
|
|
}
|
|
});
|
|
|
|
const program4 = pm.get({ // New program, with different source based on module and its injection
|
|
vs,
|
|
fs,
|
|
defines: {
|
|
MY_DEFINE: true
|
|
},
|
|
modules: [picking]
|
|
});
|
|
|
|
const program5 = pm.get({ // Cached, same as program 4, use count 2
|
|
vs,
|
|
fs,
|
|
defines: {
|
|
MY_DEFINE: true
|
|
},
|
|
modules: [picking]
|
|
});
|
|
|
|
pm.release(program1); // Cached program still available, use count 1
|
|
pm.release(program2); // Cached program deleted
|
|
pm.release(program3); // Cached program deleted
|
|
pm.release(program4); // Cached program still available, use count 1
|
|
pm.release(program5); // Cached program deleted
|
|
```
|
|
|
|
|
|
## Methods
|
|
|
|
### get(opts : Object) : Program
|
|
|
|
Get a program that fits the parameters provided. If one is already cached, return it, otherwise create and cache a new one.
|
|
`opts` can include the following (see `assembleShaders` for details):
|
|
* `vs`: Base vertex shader source.
|
|
* `fs`: Base fragment shader source.
|
|
* `defines`: Object indicating `#define` constants to include in the shaders.
|
|
* `modules`: Array of module objects to include in the shaders.
|
|
* `inject`: Object of hook injections to include in the shaders.
|
|
|
|
### `addDefaultModule(module: Object)`
|
|
|
|
Add a module that will automatically be added to any programs created by the program manager.
|
|
|
|
### `removeDefaultModule(module: Object)`
|
|
|
|
Remove a module that is automatically being added to programs created by the program manager.
|
|
|
|
### `addShaderHook(hook : String, [opts : Object])`
|
|
|
|
Creates a shader hook function that shader modules can injection code into. Shaders can call these functions, which will be no-ops by default. If a shader module injects code it will be executed upon the hook function call. This mechanism allows the application to create shaders that can be automatically extended by included shader modules.
|
|
|
|
- `hook`: `vs:` or `fs:` followed by the name and arguments of the function, e.g. `vs:MYHOOK_func(inout vec4 value)`. Hook name without arguments
|
|
will also be used as the name of the shader hook
|
|
- `opts.header` (optional): code always included at the beginning of a hook function
|
|
- `opts.footer` (optional): code always included at the end of a hook function
|
|
|
|
### `addModuleInjection(module : Object, opts : Object)`
|
|
|
|
Define a code injection for a particular hook function (defined by `addShaderHook`) and shader module. The injection code will be inserted into the hook function whenever the shader module is included.
|
|
|
|
- `module`: module object for which the injection is being defined
|
|
- `opts.hook`: the shader hook to inject into. This can be a hook function defined by `addShaderHook` or a predefined injection key (see below),
|
|
prefixed by `vs:` for the vertex shader or `fs:` for the fragment shader.
|
|
- `opts.injection`: the injection code
|
|
- `opts.order` (optional): the priority with which to inject code into the shader hook. Lower priority numbers will
|
|
be injected first
|
|
|
|
### getUniforms(program : Program) : Object
|
|
|
|
Returns an object containing all the uniforms defined for the program. Returns `null` if `program` isn't managed by the `ProgramManager`.
|
|
|
|
### release(program : Program)
|
|
|
|
Indicate that a program is no longer in use. When all references to a program are released, the program is deleted.
|
|
|
|
|