Use case

Runtime Shaders

Proposal

Currently, shader blobs emitted by impellerc do not include any versioning or validation metadata. This creates a risk when:

• Applications persist these blobs (e.g., to ship precompiled shaders),
• But impellerc or the Impeller runtime changes assumptions about layout, encoding, or expectations.

Such mismatches could lead to runtime crashes, undefined behavior, or difficult-to-diagnose bugs due to incompatible blobs being loaded.

This issue was raised during review of flutter/flutter#168294, which introduces support for loading precompiled Impeller shaders from in-memory blobs.

The same problem exists with the fragment program API, which also accepts external shader inputs.

Proposal

We should introduce in impellerc:

• A version tag (semantic or numeric) embedded in each shader blob
• A validation header or magic number for early failure detection
• Possibly a checksum or hash for corruption detection
• Runtime blob consumers (e.g., RuntimeStage, fragment program loader) should verify this metadata before accepting the blob

By doing this once in impellerc, we ensure both the mobile APIs and fragment program APIs avoid future forward-compatibility issues.

Related PR: #168294