🥮 mooncakes.io

moon_wgsl

User-facing facade for WGSL preprocess and composer utilities aligned with naga_oil.

wgsl
shader
moon add Milky2018/moon_wgsl@0.17.0
Download zip
Author
Version
0.17.0
License
Apache-2.0
Repository
Last updated
26 days ago
Downloads
334

Dependencies

README

#Milky2018/moon_wgsl

User-facing facade for WGSL preprocessing and composition.

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, 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

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"))
}

#
ComposableModuleDescriptor

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 WGSL workflow.

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

#
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, or export_wgsl. Registration mutates only this workspace. Each output operation observes a stable snapshot of the registered inputs and does not expose preprocessing, 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::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