luma.gl/docs/api-reference/webgl/sampler.md

Sampler

A Sampler object is an OpenGL Object that stores the sampling parameters for a texture access inside of a shader. While texture sampling parameters can be specified directly on textures, samplers allow them to be specified independently. Thus, by using samplers an application can render the same texture with different parameters without duplicating the texture or modifying the texture parameters.

To use a sampler, bind it to the same texture unit as a texture to control sampling for that texture. When using the higher level Model class, samplers can be specified using uniform names instead of texture indices.

For more information, see OpenGL Wiki.

Usage

Sampler inherits from Resource and supports the same use cases.

Create a new Sampler

import {Sampler} from 'luma.gl';
const sampler = new Sampler(gl, {
  parameters: {
  	[GL.TEXTURE_WRAP_S]: GL.CLAMP_TO_EDGE
  }
});

Reconfiguring a Sampler

const sampler = new Sampler(gl);
sampler.setParameters({
  [GL.TEXTURE_WRAP_S]: GL.CLAMP_TO_EDGE
});

Using Samplers via Model.draw

// Create a texture
const texture = new Texture2D(gl, ...);

// Create two samplers to sample the same texture in different ways
const sampler1 = new Sampler(gl, {parameters: {[GL.MIN_FILTER]: GL.LINEAR, ...}});
const sampler2 = new Sampler(gl, {parameters: {[GL.MIN_FILTER]: GL.NEAREST, ...}});

// The `Model` class can optionally bind samplers for each draw call
model.draw({
  uniforms: {texture1: texture, texture2: texture, ...},
  samplers: {texture1: sampler1, texture2: sampler2}
});

Using Samplers via direct bindings

const texture = new Texture2D(gl, ...);
texture.bind(0);
texture.bind(1);

// Create two samplers to sample the same texture in different ways
const sampler1 = new Sampler(gl, {parameters: {[GL.MIN_FILTER]: GL.LINEAR, ...}});
const sampler2 = new Sampler(gl, {parameters: {[GL.MIN_FILTER]: GL.NEAREST, ...}});
sampler1.bind(0);
sampler2.bind(1);

Methods

Base Class

Sampler inherits methods and members from Resource, with the following remarks:

• handle - Handle to the underlying WebGLSampler object
• getParameters uses WebGL APIs WebGLRenderingContext.getSamplerParameter
• setParameters see below.

constructor

new Sampler(gl, {parameters: {...}})

• gl - gl context
• parameters - an object where each key represents a sampler parameter and its value.

WebGL APIs gl.createSampler

delete

Frees the underlying WebGL resource

WebGL APIs gl.deleteSampler

setParameters

Sampler.setParameters(parameters)

• parameters (Object) - keys are parameters, value are values to be assigned

WebGL APIs gl.getSamplerParameter

bind

Note: Normally not called by the application. Instead use the samplers Model

Sampler.bind(unit)

• param {GLuint} unit - texture unit index return {Sampler} - returns self to enable chaining

WebGL APIs gl.bindSampler

unbind

Note: Normally not called by the application

Bind to the same texture unit as a texture to control sampling for that texture

• param {GLuint} unit - texture unit index return {Sampler} - returns self to enable chaining

Sampler Parameters

Sampler Parameter	Default	Description
GL.TEXTURE_MAG_FILTER	GL.LINEAR	texture magnification filter
GL.TEXTURE_MIN_FILTER	GL.NEAREST_MIPMAP_LINEAR	texture minification filter
GL.TEXTURE_WRAP_S	GL.REPEAT	texture wrapping function for texture coordinate s
GL.TEXTURE_WRAP_T	GL.REPEAT	texture wrapping function for texture coordinate t
GL.TEXTURE_WRAP_R WebGL2	GL.REPEAT	texture wrapping function for texture coordinate r
`GL_TEXTURE_MAX_ANISOTROPY	fLargest
GL.TEXTURE_BASE_LEVEL WebGL2	0	Texture mipmap level
GL.TEXTURE_MAX_LEVEL WebGL2	1000	Maximum texture mipmap array level
GL.TEXTURE_COMPARE_FUNC WebGL2	GL.LEQUAL	texture comparison function
GL.TEXTURE_COMPARE_MODE WebGL2	GL.NONE	whether r tex coord should be compared to depth texture
GL.TEXTURE_MIN_LOD WebGL2	-1000	minimum level-of-detail value
GL.TEXTURE_MAX_LOD WebGL2	1000	maximum level-of-detail value

Texture Magnification Filter

Controls how a pixel is textured when it maps to less than one texel.

Parameter: GL.TEXTURE_MAG_FILTER

Value	Description
GL.LINEAR (default)	interpolated texel
GL.NEAREST	nearest texel

• GL.NEAREST is faster than GL.LINEAR, but is not as smooth.

Texture Minification Filter

Controls how a pixel is textured maps to more than one texel.

ParameterL GL.TEXTURE_MIN_FILTER

Value	Description
GL.LINEAR	interpolated texel
GL.NEAREST	nearest texel
GL.NEAREST_MIPMAP_NEAREST	nearest texel in closest mipmap
GL.LINEAR_MIPMAP_NEAREST	interpolated texel in closest mipmap
GL.NEAREST_MIPMAP_LINEAR (default)	average texel from two closest mipmaps
GL.LINEAR_MIPMAP_LINEAR	interpolated texel from two closest mipmaps

Texture Wrapping

Controls how texture coordinates outside of the [0, 1] range are sampled.

• Parameters: GL.TEXTURE_WRAP_S, GL.TEXTURE_WRAP_T, GL.TEXTURE_WRAP_R

Value	Description
GL.REPEAT (default)	use fractional part of texture coordinates
GL.CLAMP_TO_EDGE	clamp texture coordinates
GL.MIRRORED_REPEAT	use fractional part of texture coordinate if integer part is odd, otherwise 1 - frac

Texture Comparison Mode

Specifies the texture comparison mode for currently bound depth textures (i.e. textures whose internal format is GL.DEPTH_COMPONENT_*)

• Parameters GL.TEXTURE_COMPARE_MODE

Value	Description
GL.NONE (default)	no comparison of r coordinate is performed
GL.COMPARE_REF_TO_TEXTURE	interpolated and clamped r texture coordinate is compared to currently bound depth texture, result is assigned to the red channel

Texture Comparison Function

Parameter: GL.TEXTURE_COMPARE_FUNC

`Value	Computed result
GL.LEQUAL (default)	result = 1.0 0.0, r <= D t r > D t
GL.GEQUAL	result = 1.0 0.0, r >= D t r < D t
GL.LESS	result = 1.0 0.0, r < D t r >= D t
GL.GREATER	result = 1.0 0.0, r > D t r <= D t
GL.EQUAL	result = 1.0 0.0, r = D t r ≠ D t
GL.NOTEQUAL	result = 1.0 0.0, r ≠ D t r = D t
GL.ALWAYS	result = 1.0
GL.NEVER	result = 0.0