@react-vertex/uniform-hooks v2.1.0

@react-vertex/uniform-hooks

Documentation and Examples

React hooks for working with WebGL uniforms. More info on WebGL uniforms on MDN.

Install via npm:

npm install @react-vertex/uniform-hooks

Importing:

import {
  useUniformSampler2d,

  useUniform1f,
  useUniform1fv, 
  useUniform1i,  
  useUniform1iv,

  useUniform2f,
  useUniform2fv,
  useUniform2i,
  useUniform2iv,
  
  useUniform3f,
  useUniform3fv,
  useUniform3i,
  useUniform3iv,
  
  useUniform4f,
  useUniform4fv,
  useUniform4i,
  useUniform4iv,
  
  useUniformMatrix2fv,
  useUniformMatrix3fv,
  useUniformMatrix4fv,
} from '@react-vertex/uniform-hooks'

useUniformSampler2d(gl, program, name, texture, unit) => updateUniform

React hook for setting up a sampler uniform to make a texture available in your shader.

Arguments:

gl: A WebGL context.

program: The WebGLProgram you want to attach the uniform to.

name: String name of the uniform as used in the shaders for the supplied program.

texture: a WebGLTexture to bind to.

unit: An integer. Specifies the unit (slot) where the texture is accessed.

Returns:

updateUniform: A function to call to update the unit from elsewhere in your app (rarely needed). The uniform will update on its own if you change the input value as well, but this can be handy in some cases. In general there is no need to use the return value from useUniformSampler2d.

Example Usage:

import { useProgram } from '@react-vertex/shader-hooks'
import { useUniformSampler2d } from '@react-vertex/uniform-hooks'
import { useTexture2d } from '@react-vertex/texture-hooks'
import tilesDiffUrl from 'static/textures/tiles_diff.png'

...
  const program = useProgram(gl, vert, frag)

  const [texDiff] = useTexture2d(gl, tilesDiffUrl)
  useUniformSampler2d(gl, program, 'texDiff', texDiff, 0) // tell program to read the from unit 0
...

useUniform[1234][fi]v(gl, program, name, value, ...) => updateUniform

React hooks for WebGL vector, float and integer uniforms. These hooks will update the uniform when the value changes. They will also warn if the location does not exist in the program e.g. you have a typo in your shader. The hooks ending in v take array values (see examples below).

Arguments:

gl: A WebGL context.

program: The WebGLProgram you want to attach the uniform to.

name: String name of the uniform as used in the shaders for the supplied program.

value(s): value(s) for the uniform. You can use regular JavaScript arrays for those that accept arrays.

Returns:

updateUniform: A function to call to update the uniform from elsewhere in your app. The uniform will update on its own if you change the input value as well, but this can be handy in some cases. The call signature is the same as what you used to set the hook. In most cases you don't need the return value from the uniform hooks.

Example Usage:

import { useProgram } from '@react-vertex/shader-hooks'
import { ... } from '@react-vertex/uniform-hooks'

...
  const program = useProgram(gl, vert, frag)

  // glsl: uniform float name;
  useUniform1f(gl, program, 'name', 40.5)
  useUniform1fv(gl, program, 'name', [40.5])

  // glsl: uniform int name;
  useUniform1i(gl, program, 'name', 100)
  useUniform1iv(gl, program, 'name', [100])

  // glsl: uniform vec2 name; 
  useUniform2f(gl, program, 'name', 40.5, 50.5)
  useUniform2fv(gl, program, 'name', [40.5, 50.5])
  useUniform2i(gl, program, 'name', 100, 200)
  useUniform2iv(gl, program, 'name', [100, 200])

  // glsl: uniform vec3 name; 
  useUniform3f(gl, program, 'name', 40.5, 50.5, 60.5)
  useUniform3fv(gl, program, 'name', [40.5, 50.5, 60.5])
  useUniform3i(gl, program, 'name', 100, 200, 300)
  useUniform3iv(gl, program, 'name', [100, 200, 300])

  // glsl: uniform vec4 name; 
  useUniform4f(gl, program, 'name', 40.5, 50.5, 60.5, 70.5)
  useUniform4fv(gl, program, 'name', [40.5, 50.5, 60.5, 70.5])
  useUniform4i(gl, program, 'name', 100, 200, 300, 400)
  useUniform4iv(gl, program, 'name', [100, 200, 300, 400])
...

useUniformMatrix[234]fv(gl, program, name, value) => updateUniform

React hooks for WebGL matrix uniforms. These hooks will update the uniform when the value changes. They will also warn if the location does not exist in the program e.g. you have a typo in your shader.

Arguments:

gl: A WebGL context.

program: The WebGLProgram you want to attach the uniform to.

name: String name of the uniform as used in the shaders for the supplied program.

value: The matrix value for the uniform.

Returns:

updateUniform: A function to call to update the uniform from elsewhere in your app. The uniform will update on its own if you change the input value as well, but this can be handy in some cases. The call signature is the same as what you used to set the hook. In most cases you don't need the return value from the uniform hooks.

Example Usage:

import { mat4 } from 'gl-matrix'
import { useProgram } from '@react-vertex/shader-hooks'
import { useUniformMatrix4fv } from '@react-vertex/uniform-hooks'

...
  const program = useProgram(gl, vert, frag)

  const model = useRef(mat4.create())
  useUniformMatrix4fv(gl, program, 'uModel', model.current)
...