🥮 mooncakes.io

    moon_wgsl

    User-facing facade for WGSL preprocessing, composition, and WESL compilation.

    wgsl
    shader
    Download zip
    Author
    Version
    0.17.2
    License
    Apache-2.0
    Repository
    Last updated
    1 hour ago
    Downloads
    345

    Dependencies

    #Milky2018/moon_wgsl

    User-facing facade for WGSL preprocessing, composition, and WESL compilation.

    Install this module when your application wants naga-oil-style shader preprocessing without importing internal parser, IR, writer, or rewrite packages directly.

    Composer is facade-owned and opaque. Its complete workflow is deliberately small: register sources/modules, prepare, compose, compile WESL, and export. Internal preprocessing stages, Compose graphs, semantic IR, writer plans, and parity entry points are not methods on this type. Tooling that needs those details imports Milky2018/moon_wgsl_naga_oil/diagnostics explicitly.

    The implementation delegates to:

    • Milky2018/wgsl for WGSL parsing, IR, and validation
    • Milky2018/moon_wgsl_naga_oil for preprocessing and composition
    • Milky2018/moon_wesl for WESL resolution and compilation

    Legacy internal package paths from the old single-module layout are not preserved. Import lower-level modules explicitly when you need their ownership boundary.

    WgslComposeOptions::default() contains no project-specific shader values. Use bevy_wgsl_value_defines() explicitly when composing Bevy shaders.

    For a source that uses a backend-specific var<immediate> struct global, add a structured specialization to the compose options. It names the source and global declaration before import linking and must provide every struct field:

    ///|
    test "configure an immediate specialization" {
      let options = {
        ..WgslComposeOptions::default(),
        immediate_specializations: [
          WgslImmediateSpecialization("root.wgsl", "constants", {
            "max_mip_level": UInt(12),
          }),
        ],
      }
      assert_eq(options.immediate_specializations.length(), 1)
    }

    Composition lowers the declaration to a concrete WGSL const; callers do not need to patch the emitted shader text.

    ///|
    test "compose a shader through the facade" {
      let composer = Composer::default()
      let util_source =
        #|#define_import_path test::util
        #|
        #|fn value() -> u32 {
        #|  return 1u;
        #|}
        #|
      composer.register_source("util.wgsl", util_source)
      let root_source =
        #|#import test::util::value
        #|
        #|fn root() -> u32 {
        #|  return value();
        #|}
        #|
      composer.register_source("root.wgsl", root_source)
      let source = composer.compose("root.wgsl", WgslComposeOptions::default())
      assert_true(source.contains("fn root"))
    }

    The same source registry can hold WESL and WGSL modules. Call compile_wesl explicitly when the root uses WESL imports:

    ///|
    test "compile WESL through the facade" {
      let composer = Composer::default()
      let util_source =
        #|fn double(value: f32) -> f32 {
        #|  return value * 2.0;
        #|}
        #|
      composer.register_source("shaders/util.wgsl", util_source)
      let root_source =
        #|import super::util::double;
        #|
        #|@fragment
        #|fn fragment(value: f32) -> f32 {
        #|  return double(value);
        #|}
        #|
      composer.register_source("shaders/root.wesl", root_source)
      let source = composer.compile_wesl(
        "shaders/root.wesl",
        CompileOptions::default(),
      )
      assert_true(source.contains("fn fragment"))
    }

    For each imported module, the facade prefers <path>.wesl, then <path>.wgsl. Applications that need custom resolvers, source maps, WESL AST access, or detailed WESL diagnostics should import Milky2018/moon_wesl directly.

    CompileOptions

    source

    ComposableModuleDescriptor

    source

    Feature

    source

    Features

    source

    ImportDefWithOffset

    source

    ImportDefinition

    source

    MetadataError

    source

    PreparedWgslSource

    source

    PreprocessError

    source

    PreprocessOutput

    source

    Preprocessor

    source

    PreprocessorMetaData

    source

    ShaderDefValue

    source

    WgslComposeOptions

    source

    WgslDiagnostic

    source

    WgslDiagnosticSeverity

    source

    WgslDirectives

    source

    WgslExportOptions

    source

    WgslExportOutput

    source

    WgslImmediateSpecialization

    source

    Concrete values for one var<immediate> struct global.

    rel_path and global_name identify the declaration before imports are linked. Every field in the struct must have a value.

    WgslSourceCatalogEntry

    source

    WgslSourceFile

    source

    WgslSourceMapEntry

    source

    WgslSourceOriginEntry

    source

    WgslSourceOriginKind

    source

    WgslSourceRegistry

    source

    WgslSymbolRedirect

    source

    WgslError

    source
    pub(all) suberror WgslError {
      WorkflowFailed(String)
    }

    Error reported by the user-facing shader workflow.

    Lower-level parser, resolver, compiler, composer, and writer errors are deliberately collapsed at this boundary. Callers that need stage-specific diagnostics should use the dedicated naga-oil diagnostics package or Milky2018/moon_wesl directly.

    WgslError::message

    source
    fn WgslError::message(self : WgslError) -> String

    Composer

    source
    pub struct Composer {
      // private fields
    }

    A user-facing WGSL workspace.

    Register all sources and modules before calling prepare, compose, compile_wesl, or export_wgsl. Registration mutates only this workspace. Each output operation observes a stable snapshot of the registered inputs and does not expose preprocessing, resolution, graph, IR, writer-plan, or parity stages.

    Composer::add_module

    source

    Register a named composable module.

    Composer::clear_sources

    source
    fn Composer::clear_sources(self : Composer) -> Unit

    Remove every registered source and composable module.

    Composer::compile_wesl

    source
    fn Composer::compile_wesl(self : Composer, root_rel_path : String, options : 
    CompileOptions    ) -> String raise WgslError

    Compile a registered WESL root and its imports into standard WGSL.

    Imports are resolved from this composer's source registry. For each module, a .wesl source is preferred over a .wgsl source with the same stem.

    Composer::compose

    source
    fn Composer::compose(self : Composer, rel_path : String, options : 
    WgslComposeOptions    ) -> String raise WgslError

    Compose one registered source into runtime-valid WGSL.

    Composer::default

    source
    fn Composer::default() -> Composer

    Composer::export_wgsl

    source

    Compose and export one registered source with source-map metadata.

    Composer::prepare

    source

    Resolve and preprocess a registered source without exposing internal stages.

    Composer::register_source

    source
    fn Composer::register_source(self : Composer, rel_path : String, source : String) -> Unit

    Replace or add one source under its normalized relative path.

    Composer::register_source_files

    source
    fn Composer::register_source_files(self : Composer, source_files : Array[
    WgslSourceFile    ]) -> Unit

    Replace or add a batch of source files.

    Composer::remove_module

    source
    fn Composer::remove_module(self : Composer, name : String) -> Unit

    Remove a composable module when it exists.

    apply_wgsl_ifdefs_strict

    source

    apply_wgsl_template_consts

    source
    fn apply_wgsl_template_consts(source : String, value_defines : Map[String, 
    ShaderDefValue    ]) -> String

    bevy_wgsl_value_defines

    source

    collect_wgsl_source_local_shader_defines

    source
    fn collect_wgsl_source_local_shader_defines(source : String) -> Map[String, 
    ShaderDefValue    ]

    default_shader_rel_path_for_module_path

    source
    fn default_shader_rel_path_for_module_path(module_path : String) -> String

    get_preprocessor_metadata

    source
    fn get_preprocessor_metadata(source : String, allow_defines? : Bool, collect_import_uses? : Bool) -> 
    PreprocessorMetaData     raise 
    MetadataError

    normalize_shader_rel_path

    source
    fn normalize_shader_rel_path(rel : String) -> String

    wgsl_source_define_import_path

    source
    fn wgsl_source_define_import_path(source : String) -> String?

    Source Files

    Powered by MoonBit

    Site sourceReport issuePackagesBuild queueSkillsStatistics

    © 2026 mooncakes.io