[BREAKING] Feature: KHR_materials_anisotropy #7668

emadurandal · 2025-05-14T10:12:17Z

This PR is an implementation of KHR_materials_anisotropy.

Notice

The valid value range for the anisotropy property of StandardMaterial is changed from [-1,1] to [0,1].
The visual behavior differs from the existing anisotropy implementation.

I also noticed during implementation that there seems to be a discrepancy in the results in the implementation variation of the getTBN() shader function. The code for the “object space TBN” case seems to compute a different (possibly incorrect) result than the codes for the other branches. When going through the “object space TBN” branch, the result of the anisotropic direction is the opposite of what is expected.

https://github.com/playcanvas/engine/blob/48a2276427d7860354655fdcc59f10572459e5ff/src/scene/shader-lib/chunks-glsl/lit/frag/TBN.js

I confirm I have read the contributing guidelines and signed the Contributor License Agreement.

Copilot

Pull Request Overview

This PR introduces a draft implementation for KHR_materials_anisotropy in the WebGL(GLSL) pipeline, updating material properties, shaders, parsers, and examples to support anisotropy and its rotation.

Added new material properties and texture maps for anisotropy and anisotropy rotation.
Updated shader chunks and programs to utilize anisotropy parameters and integrate with the GGX specular branch.
Extended the GLB material parser to handle the new anisotropy extension and updated relevant tests and examples.

Reviewed Changes

Copilot reviewed 22 out of 22 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
utils/plugins/rollup-types-fixup.mjs	Added new anisotropy-related material property definitions.
test/scene/materials/standard-material.test.mjs	Extended tests to cover anisotropy and its associated properties.
src/scene/shader-lib/programs/standard.js	Integrated anisotropy defines into the shader generation for GGX specular.
src/scene/shader-lib/chunks-glsl/standard/frag/stdFrontEnd.js	Included anisotropy shader chunks in the fragment front-end.
src/scene/shader-lib/chunks-glsl/standard/frag/stdDeclaration.js	Declared anisotropy uniforms and texture allocations.
src/scene/shader-lib/chunks-glsl/standard/frag/anisotropyRotation.js & anisotropy.js	Added new shader functions for sampling anisotropy and its rotation.
src/scene/shader-lib/chunks-glsl/lit/frag/reflDirAniso.js	Updated reflection direction calculation to incorporate anisotropic effects.
src/scene/shader-lib/chunks-glsl/lit/frag/lightSpecularAnisoGGX.js	Modified specular computation logic to account for anisotropy blending.
src/scene/materials/standard-material.js	Updated material property definitions and parameter setting for anisotropy.
src/framework/parsers/glb-parser.js	Extended GLB parsing to support anisotropy material extension.
examples/*	Added new examples to demonstrate anisotropy strength, rotation, disc and lamp features.

src/framework/parsers/glb-parser.js

src/scene/shader-lib/chunks-glsl/lit/frag/lightSpecularAnisoGGX.js

Maksims · 2025-05-15T07:18:08Z

Why this PR is marked as "breaking"? If there are breaking changes to APIs, please document them in first post. We always try to avoid breaking anything public, and if that is not possible, then provide a deprecation path, so old ways still work and devs have time to migrate without forcing them with broken state.

emadurandal · 2025-05-15T14:16:56Z

@Maksims I may have used the wrong meaning of “breaking”. There are no API-disruptive changes in this PR. I just wanted to communicate that the appearance of anisotropic reflections could be different than before. If it is inappropriate to add “breaking” in such a case, I will remove it.
(I am new to PlayCanvas development and am still getting used to the conventions.)

mvaligursky · 2025-05-15T14:31:35Z

This looks pretty great! Some feedback:

I would only add a single texture, instead of anisotropyMap and anisotropyRotationMap. Data is always stored in a single texture, so no need for it to consume two samplers.
Similarly then for the new chunks - we should just have one, and add defines as needed to control its behavior.

mvaligursky · 2025-05-15T14:32:41Z

I agree this should be marked as BREAKING, as the visuals of this feature enabled will be different then before. We use this flag to bring it up to attention of our users.

emadurandal · 2025-05-16T03:04:45Z

Some feedback:

Thank you for the feedback.
Please wait a moment while I modify the code.
If we were to use a single Sampler, we would not be able to specify the channel in MapChannel.
It will be fixed in the rg channel for Rotation and in the b channel for Strength.

mvaligursky · 2025-05-21T11:53:04Z

src/scene/shader-lib/chunks-glsl/standard/frag/anisotropy.js

+#endif
+
+    #ifdef STD_ANISOTROPY_TEXTURE
+    dAnisotropy *= texture2DBias({STD_ANISOTROPY_TEXTURE_NAME}, {STD_ANISOTROPY_TEXTURE_UV}, textureBias).b;


only sample the texture one time to a temporary and get the data out, instead of twice.

Fixed at d1504aa

mvaligursky · 2025-05-21T11:54:59Z

src/scene/shader-lib/chunks-glsl/standard/frag/stdFrontEnd.js

@@ -84,6 +84,15 @@ export default /* glsl */`
            #include "clearCoatNormalPS"
        #endif

+        // anisotropy
+        #ifdef LIT_SPECULAR


it'd be clener to write #if defined(LIT_SPECULAR) && defined() ....

Fixed at d9bbc21

mvaligursky · 2025-05-21T11:55:07Z

src/scene/shader-lib/chunks-glsl/standard/frag/stdFrontEnd.js

@@ -197,6 +206,14 @@ export default /* glsl */`
                litArgs_clearcoat_worldNormal = ccNormalW;
            #endif

+            #ifdef LIT_SPECULAR


Fixed at d9bbc21

mvaligursky · 2025-05-21T11:56:30Z

src/scene/shader-lib/chunks-wgsl/standard/frag/anisotropy.js

+#endif
+
+#ifdef STD_ANISOTROPY_TEXTURE
+    dAnisotropy *= textureSampleBias({STD_ANISOTROPY_TEXTURE_NAME}, {STD_ANISOTROPY_TEXTURE_NAME}Sampler, {STD_ANISOTROPY_TEXTURE_UV}, uniform.textureBias).b;


same here, sample the texture once

Fixed at d1504aa

mvaligursky · 2025-05-21T11:57:05Z

src/scene/shader-lib/chunks-wgsl/standard/frag/stdFrontEnd.js

@@ -85,6 +85,15 @@ export default /* wgsl */`
            #include "clearCoatNormalPS"
        #endif

+        // anisotropy
+        #ifdef LIT_SPECULAR


one liner define pls.

Fixed at d9bbc21

mvaligursky · 2025-05-21T11:57:33Z

src/scene/shader-lib/collections/shader-chunks-glsl.js

@@ -13,6 +13,7 @@ import blurVSMPS from '../chunks-glsl/lit/frag/blurVSM.js';
 import clearCoatPS from '../chunks-glsl/standard/frag/clearCoat.js';
 import clearCoatGlossPS from '../chunks-glsl/standard/frag/clearCoatGloss.js';
 import clearCoatNormalPS from '../chunks-glsl/standard/frag/clearCoatNormal.js';
+import anisotropyPS from '../chunks-glsl/standard/frag/anisotropy.js';


these are sorted alphabetically

Fixed at 6bdd3b2

mvaligursky · 2025-05-21T11:57:39Z

src/scene/shader-lib/collections/shader-chunks-glsl.js

@@ -187,6 +188,7 @@ const shaderChunksGLSL = {
    clearCoatPS,
    clearCoatGlossPS,
    clearCoatNormalPS,
+    anisotropyPS,


these are sorted alphabetically

Fixed at 6bdd3b2

mvaligursky · 2025-05-21T11:57:46Z

src/scene/shader-lib/collections/shader-chunks-wgsl.js

@@ -182,6 +183,7 @@ const shaderChunksWGSL = {
    clearCoatPS,
    clearCoatGlossPS,
    clearCoatNormalPS,
+    anisotropyPS,


these are sorted alphabetically

Fixed at 6bdd3b2

mvaligursky · 2025-05-21T11:57:49Z

src/scene/shader-lib/collections/shader-chunks-wgsl.js

@@ -13,6 +13,7 @@ import blurVSMPS from '../chunks-wgsl/lit/frag/blurVSM.js';
 import clearCoatPS from '../chunks-wgsl/standard/frag/clearCoat.js';
 import clearCoatGlossPS from '../chunks-wgsl/standard/frag/clearCoatGloss.js';
 import clearCoatNormalPS from '../chunks-wgsl/standard/frag/clearCoatNormal.js';
+import anisotropyPS from '../chunks-wgsl/standard/frag/anisotropy.js';


these are sorted alphabetically

Fixed at 6bdd3b2

mvaligursky · 2025-05-21T11:58:49Z

This looks great! I added a bunch or small comments, should be easy to wrap it up now.

…rial#anisotropy

…ed() ...." form.

emadurandal · 2025-05-21T12:38:48Z

Thank you for the comments. All fixed.

mvaligursky · 2025-05-21T12:41:36Z

by the way, you can run npm run lint -- --fix to fix most of the lint issues automatically

mvaligursky

Great work, thanks!

emadurandal added 15 commits May 14, 2025 11:37

add anisotropyRotation property

768d6c2

change calcLightSpecular to adapt to KHR_materials_anisotropy

9ff9bb7

change getReflDir to adapt to KHR_materials_anisotropy

5d62394

add anisotropyRotation and anisotropyMap to STANDARD_MAT_PROPS

0ca3ec9

introduce dAnisotropy and dAnisotropyRotation variables

b9ae82d

add texture_anisotropyMap

e1c54a2

add anisotropyMapChannel

5073267

add anisotropyRotation.js

55f4421

add properties of anisotropyMap

ff27f10

add extensionAnisotropy function to glb-parser.js

e618525

fix some code

b2abb20

add anisotropy-strength and anisotropy rotation example

1cba2bc

add anisotropy-lamp and anisotropy-disc example

9e8d960

fix: TBN calculation for LIT_GGX_SPECULAR(anisotropy)

1d400f2

adjust entity angles of examples

9186b24

vercel bot deployed to Preview May 14, 2025 10:13 View deployment

emadurandal mentioned this pull request May 14, 2025

Implement KHR_materials_anisotropy glTF extension support #6135

Closed

willeastcott requested review from mvaligursky and Copilot May 14, 2025 10:18

willeastcott added feature area: graphics Graphics related issue labels May 14, 2025

Copilot AI reviewed May 14, 2025

View reviewed changes

src/framework/parsers/glb-parser.js Outdated Show resolved Hide resolved

src/scene/shader-lib/chunks-glsl/lit/frag/lightSpecularAnisoGGX.js Show resolved Hide resolved

remove anisotropyRotationMap

72abe36

vercel bot deployed to Preview May 16, 2025 05:29 View deployment

fix: test for anisotropy

9a83c63

mvaligursky reviewed May 21, 2025

View reviewed changes

fix: material.anisotropy -> material.anisotropyIntensity

bc2cc20

vercel bot deployed to Preview May 21, 2025 12:06 View deployment

add Debug.deprecated to both the getter and setter of pc.StandardMate…

29f56d6

…rial#anisotropy

vercel bot deployed to Preview May 21, 2025 12:15 View deployment

reduce texture fetching

d1504aa

vercel bot deployed to Preview May 21, 2025 12:21 View deployment

Stop #ifdef nesting and make them "#if defined(LIT_SPECULAR) && defin…

d9bbc21

…ed() ...." form.

vercel bot deployed to Preview May 21, 2025 12:27 View deployment

emadurandal added 2 commits May 21, 2025 21:31

sorted alphabetically

6bdd3b2

insert a space

27642e1

vercel bot deployed to Preview May 21, 2025 12:33 View deployment

update thumbnails of graphics_material-anisotropic example

10d3391

vercel bot deployed to Preview May 21, 2025 12:38 View deployment

fix: quotes in Debug.deprecated

ad38cb8

vercel bot deployed to Preview May 21, 2025 12:42 View deployment

mvaligursky approved these changes May 21, 2025

View reviewed changes

mvaligursky merged commit b0b7a92 into playcanvas:main May 21, 2025
7 checks passed

mvaligursky mentioned this pull request May 22, 2025

Material-anisotropic example visual difference #7698

Closed

[BREAKING] Feature: KHR_materials_anisotropy #7668

[BREAKING] Feature: KHR_materials_anisotropy #7668

Uh oh!

Conversation

emadurandal commented May 14, 2025 • edited by willeastcott Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Maksims commented May 15, 2025

Uh oh!

emadurandal commented May 15, 2025

Uh oh!

mvaligursky commented May 15, 2025

Uh oh!

mvaligursky commented May 15, 2025

Uh oh!

emadurandal commented May 16, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mvaligursky commented May 21, 2025

Uh oh!

emadurandal commented May 21, 2025

Uh oh!

mvaligursky commented May 21, 2025

Uh oh!

mvaligursky left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

emadurandal commented May 14, 2025 •

edited by willeastcott

Loading