Skip to content

Add "alphaMask" option for ImageOverlays #1372

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Nov 26, 2025
Merged

Add "alphaMask" option for ImageOverlays #1372

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
16d6c77
Add support for using an overlay layer as a mask
gkjohnson Nov 20, 2025
ec6b202
Update dts
gkjohnson Nov 20, 2025
2668c55
Remove alphaTest option
gkjohnson Nov 26, 2025
1a0ba67
Use #defines
gkjohnson Nov 26, 2025
25a3c43
Revert "Use #defines"
gkjohnson Nov 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions src/three/plugins/images/ImageOverlayPlugin.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@ export class ImageOverlayPlugin {
renderer: WebGLRenderer,
resolution?: number,
enableTileSplitting?: boolean,
alphaMask?: boolean, // false = fade to the layer below, true = use only alpha to fade all layers underneath
alphaInvert?: boolean, // false = cut inside (keep outside); true = cut outside (keep inside)
} );

addOverlay( overlay: ImageOverlay, order?: number ): void;
Expand Down
9 changes: 7 additions & 2 deletions src/three/plugins/images/ImageOverlayPlugin.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1319,11 +1319,11 @@ export class ImageOverlayPlugin {

// set the uniform array lengths
params.layerMaps.length = overlays.length;
params.layerColor.length = overlays.length;
params.layerInfo.length = overlays.length;

// assign the uniforms
params.layerMaps.value[ i ] = target !== null ? target.texture : null;
params.layerColor.value[ i ] = overlay;
params.layerInfo.value[ i ] = overlay;

material.defines.LAYER_COUNT = overlays.length;
material.needsUpdate = true;
Expand Down Expand Up @@ -1420,13 +1420,18 @@ class ImageOverlay {
color = 0xffffff,
frame = null,
preprocessURL = null,
alphaMask = false,
alphaInvert = false,
} = options;
this.imageSource = null;

this.preprocessURL = preprocessURL;
this.opacity = opacity;
this.color = new Color( color );
this.frame = frame !== null ? frame.clone() : null;
this.alphaMask = alphaMask;
this.alphaInvert = alphaInvert;

this.isReady = false;
this.isInitialized = false;

Expand Down
33 changes: 26 additions & 7 deletions src/three/plugins/images/overlays/wrapOverlaysMaterial.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ export function wrapOverlaysMaterial( material, previousOnBeforeCompile ) {

const params = {
layerMaps: { value: [] },
layerColor: { value: [] },
layerInfo: { value: [] },
};

material[ OVERLAY_PARAMS ] = params;
Expand Down Expand Up @@ -74,13 +74,16 @@ export function wrapOverlaysMaterial( material, previousOnBeforeCompile ) {
.replace( /void main\(/, value => /* glsl */`

#if LAYER_COUNT != 0
struct LayerTint {
struct LayerInfo {
vec3 color;
float opacity;

int alphaMask;
int alphaInvert;
};

uniform sampler2D layerMaps[ LAYER_COUNT ];
uniform LayerTint layerColor[ LAYER_COUNT ];
uniform LayerInfo layerInfo[ LAYER_COUNT ];
#endif

#pragma unroll_loop_start
Expand Down Expand Up @@ -126,11 +129,27 @@ export function wrapOverlaysMaterial( material, previousOnBeforeCompile ) {
smoothstep( 1.0 + wDelta, 1.0, layerUV.z );

// apply tint & opacity
tint.rgb *= layerColor[ i ].color;
tint.rgba *= layerColor[ i ].opacity * wOpacity;
tint.rgb *= layerInfo[ i ].color;
tint.rgba *= layerInfo[ i ].opacity * wOpacity;

// invert the alpha
if ( layerInfo[ i ].alphaInvert > 0 ) {

tint.a = 1.0 - tint.a;

}

// apply the alpha across all existing layers if alpha mask is true
if ( layerInfo[ i ].alphaMask > 0 ) {

diffuseColor.a *= tint.a;

} else {

// premultiplied alpha equation
diffuseColor = tint + diffuseColor * ( 1.0 - tint.a );

// premultiplied alpha equation
diffuseColor = tint + diffuseColor * ( 1.0 - tint.a );
}

#endif

Expand Down
Loading