translate library

The engine's GLSL in the dialects the web backends read: GLSL ES 3.00 for WebGL2, and the prepared GLSL and reflection WebGPU's section is made of.

Pure text in, text out, with no dart:io anywhere under it, so a browser test and a backend's own library can import it as readily as a build script. What runs a compiler is compile.dart.

Here rather than in the two backends that wrote it — P8. A project's build hook compiles its own materials for every backend, and the hook is a process that cannot resolve a package declaring the Flutter SDK, which both flutter3d_webgl and flutter3d_webgpu do. None of these files ever needed the SDK; only the packages they lived in did.

Classes

GlslBindingCount

What countGlslBindings counts in one stage's GLSL: a class rather than a record, so a later minor can count one more kind of binding.

MaterialStageBudget

The textures, samplers and uniform blocks one stage of a pipeline may bind, the engine's own bindings and a material's together (M3).

PreparedStage

One stage, ready for glslang, beside the reflection nothing downstream can recover.

StageMismatch

One way two stages of a pipeline disagree, with the names a person fixes it by.

StageMismatchKind

What kind of disagreement a StageMismatch is.

Constants

cubeDimension → const String

WebGpuTextureDimension.cube, by name.

fragmentGroup → const int

See vertexGroup.

maxInterStageVariables → const int

How many inter-stage locations WebGPU guarantees.

sectionVersion → const int

The shape of the document this writer produces.

twoDimensional → const String

WebGpuTextureDimension.twoDimensional, by name.

vertexGroup → const int

Which bind group a stage's resources live in.

Functions

assignVaryingLocations(Iterable<Set<String>> stages) → Map<String, int>

A location per varying name, over every stage in the manifest.

checkBundleAgreement({required Map<String, String> vertex, required Map<String, String> fragment}) → List<StageMismatch>

Every mismatch between the stages of a bundle that are drawn together: vertex and fragment are the GLSL of each stage by name, includes resolved, and each vertex stage is held to the fragment stage pairedFragmentStage names. Empty when they agree.

checkStd140Offsets(String name, PreparedStage prepared, Map<String, Map<String, int>> offsets) → void

Holds a packer's std140 arithmetic against glslang's own decorations.

countGlslBindings(String glsl, {Set<String> defines = const <String>{}}) → GlslBindingCount

The distinct textures and uniform blocks glsl declares (its includes already resolved), after #define, #undef, #ifdef, #ifndef, #else and #endif are applied with defines set to begin with. A directive it does not read (#if <expression>) is taken as true, which counts more rather than fewer.

decodeSectionJson(ByteData bytes) → Object?

The JSON document bytes hold, or a BundleSectionFormatException saying why they hold none: the SDK's own FormatException from the UTF-8 or JSON decoder is the one thing a section decoder would otherwise let out bare.

decodeWebGlSection(ByteData bytes) → WebGlSectionSources

The sources in bytes.

encodeWebGlSection({required Map<String, String> vertex, required Map<String, String> fragment}) → ByteData

The section bytes for vertex and fragment sources.

pairedFragmentStage(String vertex, Set<String> fragments) → String?

The fragment stage of fragments that the vertex stage vertex is drawn with in a bundle, by the names the material language and the engine give their stages, or null when its name pairs it with none.

prepareStage(String resolved, {required String from, required bool fragment, required Map<String, int> varyingLocations, List<String> ownBindings = const <String>[]}) → PreparedStage

One name, one binding. Blocks and textures share ownBindings' one name space, as they share the stage's, so a block and a texture of the material's own under one name, or an own name that one of the engine's stages binds as its own (it would be numbered as the material's in a stage that includes it), is a WgslPrepareException naming it.

requireBundleAgreement({required Map<String, String> vertex, required Map<String, String> fragment}) → void

Throws a StageAgreementException when checkBundleAgreement finds anything: what a bundle's section writer calls before it writes.

resolveIncludes(String source, GlslSources sources, {required String from, Set<String>? seen, List<String>? stack}) → String

Resolves #include <path> against sources.

scanVaryings(String resolved, {required String from, required bool fragment}) → Set<String>

Every varying resolved declares, for assignVaryingLocations to number.

translateGlsl(String source, GlslSources sources, {required String from, required bool fragment}) → String

The whole translation, for one stage.

wgslSectionDocument({required Map<String, PackedStage> vertex, required Map<String, PackedStage> fragment}) → String

The section document for vertex and fragment, as JSON text.

Typedefs

GlslSources = Map<String, String>

A source file the translator can read.

PackedStage = ({PreparedStage prepared, String wgsl})

One finished stage: the WGSL the two compilers made, and the reflection the preparation handed out.

PreparedAttribute = ({String format, int location, String name})

One vertex input the scan found.

PreparedBlock = ({int binding, int group, List<PreparedMember> members, String name, int sizeInBytes})

One uniform block and where it is bound.

PreparedMember = ({String name, int offsetInBytes, int sizeInBytes})

One member of a uniform block, laid out by std140.

PreparedSampler = ({String dimension, int group, String name, int samplerBinding, int textureBinding})

One texture-and-sampler pair and the two bindings it takes.

WebGlSectionSources = ({Map<String, String> fragment, Map<String, String> vertex})

What the section decodes to.

Exceptions / Errors

BundleSectionFormatException

A backend's section of a shader bundle that is not the document its decoder reads: not UTF-8, not JSON, or missing a field.

GlslTranslateException

Raised when translation cannot continue. Carries the file it happened in, because an error naming only a line number is an error in nineteen hundred lines of identical-looking GLSL.

StageAgreementException

A bundle the writer refused because the stages of one of its pipelines disagree: every StageMismatch found, each naming both stages.

WgslPrepareException

Raised when a stage cannot be prepared.

WgslSectionException

Raised when a prepared stage cannot be turned into a section entry.