NZSL Modules and imports

NZSL modules

Each .nzsl file defines a module as its first statement.

Example:

[nzsl_version("1.0")]
module;

This is required as it gives two very important pieces of information to the compiler:

1. The NZSL version this file was written against (currently only 1.0 is available but this is expected to change in the future).
2. The module name, if any.

Here we are declaring an anonymous module, which is common for shaders directly given to the application/compiler, but giving it a name makes it importable in other shader sources, example:

Debug.nzsl:

[nzsl_version("1.0")]
module Debug;

[export]
fn GetDebugColor() -> vec3[f32]
{
    return vec3[f32](0.0, 1.0, 0.0);
}

Forward.nzsl:

[nzsl_version("1.0")]
module;

import GetDebugColor from Debug;

struct FragOut
{
    [location(0)] color: vec3[f32]
}

[entry(frag)]
fn main() -> FragOut
{
    let output: FragOut;
    output.color = GetDebugColor();
    return output;
}

The keys to this system are the import statement and the [export] attributes, which work together to make functions, structs, etc. usable in other files.

So, how does it work?

Import

import statements can appear anywhere in a source file and can import from 1 to N identifiers exported in another module.

Modules are exclusively referenced by the name they defined in their module directive, their folder or filename don't play any role in this.