Skip to content

Commit 25d0b83

Browse files
committed
Extract built-in shader packages for editor tooling.
1 parent 21a2dda commit 25d0b83

7 files changed

Lines changed: 258 additions & 3 deletions

File tree

‎crates/processing_pyo3/README.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,21 @@ $ python
2323
>>> processing_py.size(500, 500)
2424
```
2525

26+
### Shader editor support
27+
28+
The `processing` and `lygia` WESL packages are built into the library. To have
29+
[wgsl-analyzer](https://github.com/wgsl-analyzer/wgsl-analyzer) resolve
30+
`import processing::...` and `import lygia::...` in your sketch's shaders:
31+
32+
```
33+
$ python -m processing_py shaders init
34+
```
35+
36+
This writes the packages into the virtual environment and creates (or updates)
37+
`wesl.toml` in the current directory to point at them. Pass `--vendor`, or run
38+
without an environment, to write them to `.processing_py/shaders` instead.
39+
Rerun after upgrading processing-py.
40+
2641
## Acknowledgements
2742

2843
Thank you to [Faruk Hammoud](https://github.com/FarukHammoud) for generously handing over the `processing-py` name. Their original [processing_py](https://github.com/FarukHammoud/processing_py) project, a Python graphics library based on Processing, was published under this name from 2020 to 2021 (versions 0.1.0–0.3.7).

‎crates/processing_pyo3/processing_py/__init__.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@
1818
import importlib as _importlib
1919
math = _importlib.import_module(f"{__name__}.math") # noqa: E402
2020
from .math import * # noqa: E402,F401,F403
21+
from ._shaders import shader_workspace # noqa: E402,F401
2122

2223
# global var handling. for wildcard import of our module, we copy into globals, otherwise
2324
# we dispatch to get attr and call the underlying getter method
Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
import argparse
2+
3+
from ._shaders import shader_packages, shader_workspace
4+
5+
6+
def main(argv=None):
7+
parser = argparse.ArgumentParser(prog="python -m processing_py")
8+
commands = parser.add_subparsers(dest="command", required=True)
9+
10+
shaders = commands.add_parser("shaders", help="built-in WESL packages")
11+
shaders_commands = shaders.add_subparsers(dest="shaders_command", required=True)
12+
13+
init = shaders_commands.add_parser(
14+
"init", help="create or update wesl.toml so editors resolve processing:: and lygia::"
15+
)
16+
init.add_argument("dir", nargs="?", default=".")
17+
init.add_argument(
18+
"--vendor",
19+
action="store_true",
20+
help="write the packages to DIR/.processing_py/shaders instead of the virtual environment",
21+
)
22+
23+
shaders_commands.add_parser("path", help="write the packages and print where they are")
24+
25+
args = parser.parse_args(argv)
26+
if args.shaders_command == "init":
27+
print(f"wrote {shader_workspace(args.dir, vendor=args.vendor)}")
28+
else:
29+
for name, path in shader_packages().items():
30+
print(f"{name}\t{path}")
31+
32+
33+
if __name__ == "__main__":
34+
main()
Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
"""The built-in WESL packages as files, and wiring them into a project's `wesl.toml`
2+
so editor tooling (wgsl-analyzer) resolves `import processing::...` and
3+
`import lygia::...` the same way `Shader` does at runtime."""
4+
5+
import json
6+
import shutil
7+
import sys
8+
from pathlib import Path
9+
10+
from . import processing_py as _native
11+
12+
_BEGIN = "# BEGIN processing_py"
13+
_END = "# END processing_py"
14+
_VENDOR_DIR = Path(".processing_py") / "shaders"
15+
16+
17+
def _default_dir(base):
18+
# a virtual environment is per project and replaced along with the install
19+
if sys.prefix != sys.base_prefix:
20+
return Path(sys.prefix) / "share" / "processing_py" / "shaders"
21+
return base / _VENDOR_DIR
22+
23+
24+
def shader_packages(dest=None):
25+
"""Write the built-in WESL packages under `dest` and return `{name: directory}`.
26+
27+
`dest` defaults to the virtual environment, or `.processing_py/shaders` in the
28+
current directory without one.
29+
"""
30+
dest = Path(dest).resolve() if dest is not None else _default_dir(Path.cwd())
31+
written = {}
32+
for name, files in _native._shader_packages().items():
33+
target = dest / name
34+
if target.exists():
35+
shutil.rmtree(target)
36+
for rel, contents in files.items():
37+
path = target / rel
38+
path.parent.mkdir(parents=True, exist_ok=True)
39+
path.write_text(contents, encoding="utf-8")
40+
written[name] = target
41+
return written
42+
43+
44+
def _toml_path(path, base):
45+
try:
46+
p = path.relative_to(base)
47+
except ValueError:
48+
p = path
49+
return json.dumps(p.as_posix())
50+
51+
52+
def _dependency_block(packages, base):
53+
lines = [_BEGIN]
54+
for name, path in packages.items():
55+
lines.append(f"{name} = {{ path = {_toml_path(path, base)} }}")
56+
lines.append(_END)
57+
return lines
58+
59+
60+
def _splice(text, block):
61+
lines = text.splitlines()
62+
if _BEGIN in lines:
63+
start = lines.index(_BEGIN)
64+
try:
65+
end = lines.index(_END, start)
66+
except ValueError:
67+
raise ValueError(f"`{_BEGIN}` without a matching `{_END}`") from None
68+
lines[start : end + 1] = block
69+
else:
70+
header = next(
71+
(i for i, l in enumerate(lines) if l.split("#", 1)[0].strip() == "[dependencies]"),
72+
None,
73+
)
74+
if header is None:
75+
if lines and lines[-1].strip():
76+
lines.append("")
77+
lines += ["[dependencies]", *block]
78+
else:
79+
lines[header + 1 : header + 1] = block
80+
return "\n".join(lines) + "\n"
81+
82+
83+
def _validate(text, path):
84+
try:
85+
import tomllib
86+
except ImportError:
87+
return
88+
try:
89+
doc = tomllib.loads(text)
90+
except tomllib.TOMLDecodeError as e:
91+
raise ValueError(f"updating {path} would produce invalid TOML ({e}); edit it by hand") from None
92+
if not isinstance(doc.get("dependencies"), dict):
93+
raise ValueError(f"{path}: `dependencies` is not a table")
94+
95+
96+
def shader_workspace(path=".", vendor=False):
97+
"""Create or update `wesl.toml` in `path` so the built-in `processing` and
98+
`lygia` packages resolve in the editor.
99+
100+
The packages are written into the virtual environment. With `vendor=True`,
101+
or without an environment, they go to `.processing_py/shaders` in `path`,
102+
for editors that can't see the environment or for checking them in. Rerun
103+
after upgrading processing-py. Returns the path of the `wesl.toml`.
104+
"""
105+
base = Path(path).resolve()
106+
base.mkdir(parents=True, exist_ok=True)
107+
dest = base / _VENDOR_DIR if vendor else _default_dir(base)
108+
packages = shader_packages(dest)
109+
110+
manifest = base / "wesl.toml"
111+
block = _dependency_block(packages, base)
112+
if manifest.exists():
113+
text = _splice(manifest.read_text(encoding="utf-8"), block)
114+
else:
115+
header = ['edition = "2026_pre"', 'root = "."']
116+
# keep the project's own module scan out of the packages
117+
if dest.is_relative_to(base):
118+
header.append(f'exclude = ["{dest.relative_to(base).as_posix()}/**"]')
119+
text = "\n".join([*header, "", "[dependencies]", *block]) + "\n"
120+
_validate(text, manifest)
121+
manifest.write_text(text, encoding="utf-8")
122+
return manifest

‎crates/processing_pyo3/src/lib.rs‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -881,6 +881,20 @@ pub mod processing_py {
881881
Ok(())
882882
}
883883

884+
/// The built-in WESL packages as `{package: {relative path: source}}`.
885+
#[pyfunction]
886+
fn _shader_packages(py: Python<'_>) -> PyResult<Bound<'_, PyDict>> {
887+
let packages = PyDict::new(py);
888+
for package in processing_render::material::custom::shader_packages() {
889+
let files = PyDict::new(py);
890+
for (path, contents) in package.files {
891+
files.set_item(path, contents)?;
892+
}
893+
packages.set_item(package.name, files)?;
894+
}
895+
Ok(packages)
896+
}
897+
884898
#[pyfunction]
885899
#[pyo3(pass_module)]
886900
fn window_title(module: &Bound<'_, PyModule>, title: &str) -> PyResult<()> {

‎crates/processing_render/build.rs‎

Lines changed: 20 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
use std::path::Path;
2+
13
// packages wesl libraries for processing and lygia
24
// note that bevy does not (as of yet) understand how to use these packages
35
// they are, instead, used by us as part of shader pre-processing in the
@@ -9,9 +11,25 @@ fn main() {
911
.build_artifact()
1012
.expect("failed to build processing package artifact");
1113

12-
wesl::PkgBuilder::new("lygia")
14+
let mut lygia = wesl::PkgBuilder::new("lygia")
1315
.scan_root("../../lygia")
14-
.expect("failed to scan Lygia WESL files")
16+
.expect("failed to scan Lygia WESL files");
17+
wesl_only(&mut lygia.root, Path::new("../../lygia"));
18+
lygia.root.submodules.retain(|sub| sub.name != "test");
19+
lygia
1520
.build_artifact()
1621
.expect("failed to build Lygia package artifact");
1722
}
23+
24+
// lygia's manifest includes `**/*.wesl` only; the scan also picks up its legacy `.wgsl`
25+
fn wesl_only(module: &mut wesl::Module, path: &Path) {
26+
if !path.with_extension("wesl").is_file() {
27+
module.source.clear();
28+
}
29+
for sub in &mut module.submodules {
30+
wesl_only(sub, &path.join(&sub.name));
31+
}
32+
module
33+
.submodules
34+
.retain(|sub| !sub.source.is_empty() || !sub.submodules.is_empty());
35+
}

‎crates/processing_render/src/material/custom.rs‎

Lines changed: 52 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,7 @@ fn specialize(
7272
// the first argument is bevy's `MaterialPipeline`; the material key rides in the pipeline key
7373
let key: CustomMaterialKey = pipeline_key.material_key.to_key();
7474
crate::material::apply_pipeline_state(descriptor, key.blend_state, key.depth_write);
75-
// two-sided unless asked otherwise, like every other mewnala material
75+
// two-sided unless asked otherwise, like every other material
7676
descriptor.primitive.cull_mode = match key.double_sided {
7777
Some(false) => Some(Face::Back),
7878
_ => None,
@@ -141,6 +141,57 @@ impl wesl::Resolver for ProcessingResolver<'_> {
141141
}
142142
}
143143

144+
// wgsl-analyzer rejects lygia's own `unstable_2025` edition.
145+
const PACKAGE_MANIFEST: &str = "edition = \"2026_pre\"\nroot = \".\"\n";
146+
147+
/// A built-in WESL package as source files, for editor tooling to resolve imports against.
148+
pub struct ShaderPackage {
149+
pub name: &'static str,
150+
/// `(path relative to the package root, contents)`
151+
pub files: Vec<(String, &'static str)>,
152+
}
153+
154+
fn package_files(pkg: &'static wesl::CodegenPkg, extra: &[(&str, &'static str)]) -> ShaderPackage {
155+
fn walk(
156+
module: &'static wesl::CodegenModule,
157+
dir: &str,
158+
files: &mut Vec<(String, &'static str)>,
159+
) {
160+
for sub in module.submodules {
161+
// a directory module has no source of its own
162+
if !sub.source.is_empty() || sub.submodules.is_empty() {
163+
files.push((format!("{dir}{}.wesl", sub.name), sub.source));
164+
}
165+
walk(sub, &format!("{dir}{}/", sub.name), files);
166+
}
167+
}
168+
let mut files = vec![
169+
("wesl.toml".to_string(), PACKAGE_MANIFEST),
170+
("package.wesl".to_string(), pkg.root.source),
171+
];
172+
files.extend(
173+
extra
174+
.iter()
175+
.map(|(path, contents)| (path.to_string(), *contents)),
176+
);
177+
walk(pkg.root, "", &mut files);
178+
ShaderPackage {
179+
name: pkg.root.name,
180+
files,
181+
}
182+
}
183+
184+
/// The WESL packages every shader can import, exactly as the runtime resolves them.
185+
pub fn shader_packages() -> Vec<ShaderPackage> {
186+
vec![
187+
package_files(&processing::PACKAGE, &[]),
188+
package_files(
189+
&lygia::PACKAGE,
190+
&[("LICENSE.md", include_str!("../../../../lygia/LICENSE.md"))],
191+
),
192+
]
193+
}
194+
144195
pub(crate) fn compile_shader(source: &str) -> Result<(String, naga::Module)> {
145196
compile_shader_with_features(source, &[])
146197
}

0 commit comments

Comments
 (0)