@galacean/engine-shader-analyzer 0.0.0-stage → 2.0.0-alpha.54

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ The MIT License
2
+
3
+ Copyright (c) 2020 - present Ant Group
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in
13
+ all copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21
+ THE SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,89 @@
1
- # Temporary Holding Version
1
+ # @galacean/engine-shader-analyzer
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Standalone ShaderLab and ESSL diagnostics for authoring tools. The analyzer runs in Node.js and editors without a browser or Engine instance. Its public TypeScript declarations require no DOM library. It does not participate in runtime shader code generation.
4
+
5
+ ## JavaScript API
6
+
7
+ ```ts
8
+ import { DiagnosticSeverity, ShaderAnalyzer } from "@galacean/engine-shader-analyzer";
9
+
10
+ const { diagnostics } = ShaderAnalyzer.analyze(shaderSource, {
11
+ includeMap: {
12
+ "ShaderLibrary/Common.glsl": commonSource
13
+ }
14
+ });
15
+
16
+ const hasErrors = diagnostics.some(({ severity }) => severity === DiagnosticSeverity.Error);
17
+ ```
18
+
19
+ When diagnostics and code generation are both needed, pass the parser-owned handles from the same result directly to the compiler. No ShaderLab pass is parsed a second time:
20
+
21
+ ```ts
22
+ import { ShaderLanguage } from "@galacean/engine-core";
23
+ import { ShaderAnalyzer } from "@galacean/engine-shader-analyzer";
24
+ import { ShaderCompiler } from "@galacean/engine-shader-compiler";
25
+
26
+ const analysis = ShaderAnalyzer.analyze(shaderSource);
27
+ const compiler = new ShaderCompiler();
28
+ const programs = analysis.passes.map((pass) => compiler.generate(pass, ShaderLanguage.GLSLES300));
29
+ ```
30
+
31
+ `sourceFile` is optional metadata, not a requirement for analysis. Without it, `./Common.glsl` resolves from the logical include-registry root. Supply it when relative includes should resolve from a logical subdirectory or when an editor needs stable source attribution:
32
+
33
+ ```ts
34
+ const { diagnostics } = ShaderAnalyzer.analyze(shaderSource, {
35
+ sourceFile: "Assets/Shaders/PBR.shader",
36
+ includeMap: {
37
+ "Assets/Shaders/Common.glsl": commonSource
38
+ }
39
+ });
40
+ ```
41
+
42
+ The analyzer expands the complete root once. Diagnostics are then mapped back to the owning Shader or ShaderChunk; include fragments are never analyzed in isolation.
43
+
44
+ The parser retains neutral typed IR and stage-interface facts. GLES output types and struct-flattening constraints are checked separately by a shared GLES policy used by diagnostics and code generation. Future backends can consume the same IR with their own lowering rules; WGSL generation is not implemented.
45
+
46
+ Diagnostic lines and columns are one-based for display. Offsets are zero-based so editors can map ranges directly onto their text models.
47
+
48
+ Include expansion is limited to 128 nested includes, 8,388,608 expanded characters, and 65,536 source segments per pass. Exceeding a limit produces a source-attributed `PreprocessorError`; partial output is discarded. The same limits apply to runtime and offline compilation.
49
+
50
+ ## CLI
51
+
52
+ If the dependency packages already exist in the npm cache, install the analyzer tarball directly:
53
+
54
+ ```sh
55
+ npm install --offline ./galacean-engine-shader-analyzer-*.tgz
56
+ ```
57
+
58
+ For a fully disconnected install with an empty cache, provide the analyzer and its runtime dependency tarballs together:
59
+
60
+ ```sh
61
+ npm install --offline \
62
+ ./galacean-engine-math-*.tgz \
63
+ ./galacean-engine-design-*.tgz \
64
+ ./galacean-engine-core-*.tgz \
65
+ ./galacean-engine-shader-parser-*.tgz \
66
+ ./galacean-engine-shader-analyzer-*.tgz
67
+ ```
68
+
69
+ Analyze a file. Without `--include-root`, includes resolve from the input file's directory:
70
+
71
+ ```sh
72
+ galacean-shader-analyzer Assets/Shaders/PBR.shader
73
+ ```
74
+
75
+ Use `--include-root` when project-root include keys must resolve from a broader shader directory:
76
+
77
+ ```sh
78
+ galacean-shader-analyzer --include-root Assets/Shaders Assets/Shaders/PBR.shader
79
+ ```
80
+
81
+ Read from stdin and return structured JSON:
82
+
83
+ ```sh
84
+ galacean-shader-analyzer --json - < Assets/Shaders/PBR.shader
85
+ ```
86
+
87
+ The file argument may be omitted to read stdin. The CLI exits with `0` when there are no error diagnostics (warnings are allowed), `1` when at least one error is present, and `2` for invalid command-line usage.
88
+
89
+ Run `galacean-shader-analyzer --help` for the complete command reference.