OpenLIME

Class: ShaderLens

ShaderLens

ShaderLens implements a circular magnification lens effect with optional overlay.

Features:

  • Circular lens with smooth borders
  • Configurable lens size and position
  • Optional border with customizable color
  • Optional overlay layer with grayscale outside lens
  • Smooth transition between lens and background
  • Real-time lens movement

Technical Implementation:

  • Pixel-based distance calculations
  • Smooth border transitions
  • Alpha blending for overlays
  • WebGL 1.0 and 2.0 compatibility
  • Viewport coordinate mapping

Example usage:

// Create lens shader
const lens = new ShaderLens();

// Configure lens
lens.setLensUniforms(
    [400, 300, 100, 10],  // center at (400,300), radius 100, border 10
    [800, 600],           // viewport size
    [0.8, 0.8, 0.8, 1],   // gray border
    true                  // show border
);

// Enable overlay
lens.setOverlayLayerEnabled(true);

Advanced usage with custom configuration:

const lens = new ShaderLens({
    uniforms: {
        u_lens: { value: [0, 0, 150, 15] },
        u_border_color: { value: [1, 0, 0, 1] }  // red border
    },
    overlayLayerEnabled: true
});

GLSL Implementation Details

Key Components:

  1. Lens Function:

    • Distance-based circle calculation
    • Smooth border transitions
    • Color mixing and blending

  2. Overlay Processing:

    • Grayscale conversion
    • Alpha blending
    • Border preservation

Functions:

  • lensColor(): Handles color transitions between lens regions
  • data(): Main processing function

Uniforms:

  • {vec4} u_lens - Lens parameters [cx, cy, radius, border]
  • {vec2} u_width_height - Viewport dimensions
  • {vec4} u_border_color - Border color and alpha
  • {bool} u_border_enable - Border visibility flag
  • {sampler2D} source0 - Main texture
  • {sampler2D} source1 - Optional overlay texture

new ShaderLens( [options])

Creates a new lens shader

Parameters:
Name Type Argument Description
options ShaderLens~Options <optional>

Configuration options
Source:
Example
```javascript
// Create basic lens shader
const lens = new ShaderLens({
    label: 'MyLens',
    overlayLayerEnabled: false
});
```

Extends

Methods

addFilter(filter)

Adds a filter to the shader pipeline.

Parameters:
Name Type Description
filter Object

Filter to add
Inherited From:
Overrides:
Source:
Fires:

allUniforms()

Returns all uniform variables associated with the shader and its filters. Combines uniforms from both the base shader and all active filters into a single object.

Inherited From:
Overrides:
Source:
Returns:

Combined uniform variables

Type
Object.<string, Object>

clearFilters()

Clears all filters from the shader pipeline.

Inherited From:
Overrides:
Source:
Fires:

getUniform(name)

Gets a uniform variable by name. Searches both shader uniforms and filter uniforms.

Parameters:
Name Type Description
name string

Uniform variable name
Inherited From:
Overrides:
Source:
Returns:

Uniform object if found

Type
Object | undefined

removeFilter(name)

Removes a filter from the pipeline by name.

Parameters:
Name Type Description
name string

Name of filter to remove
Inherited From:
Overrides:
Source:
Fires:

setLensUniforms(lensViewportCoords, windowWH, borderColor, borderEnable)

Updates lens parameters and appearance

Parameters:
Name Type Description
lensViewportCoords Array.<number>

Lens parameters [centerX, centerY, radius, borderWidth]
windowWH Array.<number>

Viewport dimensions [width, height]
borderColor Array.<number>

RGBA border color
borderEnable boolean

Whether to show border
Source:

setMode(mode)

Sets the current shader mode.

Parameters:
Name Type Description
mode string

Mode identifier (must be in options.modes)
Inherited From:
Overrides:
Source:
Throws:

If mode is not recognized

Type
Error

setOverlayLayerEnabled(enabled)

Enables or disables the overlay layer When enabled, adds a second texture layer with grayscale outside lens

Parameters:
Name Type Description
enabled boolean

Whether to enable overlay
Source:

setTileSize(size)

Sets tile dimensions for shader calculations.

Parameters:
Name Type Description
size Array.<number>

[width, height] of tile
Inherited From:
Overrides:
Source:

setUniform(name, value)

Sets a uniform variable value.

Parameters:
Name Type Description
name string

Uniform variable name
value number | boolean | Array

Value to set
Inherited From:
Overrides:
Source:
Fires:
Throws:

If uniform doesn't exist

Type
Error

Type Definitions

Options

Configuration options for lens shader

Type:
  • Object
Properties:
Name Type Argument Default Description
label string <optional>
 'ShaderLens'

Display label
overlayLayerEnabled boolean <optional>
 false

Enable overlay layer
uniforms Object <optional>

Custom uniform values
Source:

Uniforms

Uniform definitions for lens shader

Type:
  • Object
Properties:
Name Type Description
u_lens Array.<number>

Lens parameters [centerX, centerY, radius, borderWidth]
u_width_height Array.<number>

Viewport dimensions [width, height]
u_border_color Array.<number>

RGBA border color [r, g, b, a]
u_border_enable boolean

Whether to show lens border
Source:

Events

update

Fired when shader state changes (uniforms, filters, etc).

Inherited From:
Overrides:
Source: