Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
PhosphorShaders::ShaderIncludeResolver Class Reference

Resolves #include directives in GLSL shader source. More...

#include <PhosphorShaders/ShaderIncludeResolver.h>

Static Public Member Functions

static QString expandIncludes (const QString &source, const QString &currentFileDir, const QStringList &includePaths, QString *outError=nullptr, QStringList *outIncludedPaths=nullptr, QStringList *outSourcePaths=nullptr)
 Expand #include directives in source.

Static Public Attributes

static constexpr int MaxIncludeDepth = 10
static constexpr qint64 MaxIncludeBytes = 1 << 20
 Largest include file, in bytes.
static constexpr qsizetype MaxExpandedSize = 16 << 20
 Largest expanded source, in UTF-16 code units.
static constexpr const char * GeneratedPreambleInclude = "p_generated.glsl"
 Reserved include name for the generated p_<id> autocomplete sidecar (plasmazones-shader-validate --emit-preamble).

Detailed Description

Resolves #include directives in GLSL shader source.

Supports:

  • #include "path" — search relative to current file's directory, then include paths
  • #include <path> — search only in include paths (e.g. global shaders dir)

An include name is always relative to a search directory: an absolute name is an error. Shader packs can come from third parties, and an absolute name would let one inline any readable file on the system.

Member Function Documentation

◆ expandIncludes()

QString PhosphorShaders::ShaderIncludeResolver::expandIncludes ( const QString & source,
const QString & currentFileDir,
const QStringList & includePaths,
QString * outError = nullptr,
QStringList * outIncludedPaths = nullptr,
QStringList * outSourcePaths = nullptr )
static

Expand #include directives in source.

Each inlined include is bracketed by PhosphorShaders::lineDirective re-anchors. A re-anchor of that shape that source already carries for its own source string, such as the one assembleEntryPoint emits after a family prologue, is honoured: the parent's re-anchor after a later include counts from it rather than from the top of the text.

Parameters
sourceRaw shader source (may contain #include "..." or #include <...>)
currentFileDirDirectory of the file that contains source
includePathsDirectories to search for includes
outErrorIf non-null, set on error (file not found, absolute name, depth or size exceeded)
outIncludedPathsIf non-null, appended with the canonical absolute path of every successfully-resolved include file. Lets callers fingerprint transitively-included headers (e.g. for cache invalidation) — without this, a cache keyed only on the top-level shader's mtime serves stale baked SPIR-V when an included header changes.
outSourcePathsIf non-null, populated as a GLSL source-string legend: element i is the path of source-string number i as referenced by the #line <n> <i> directives this resolver emits around each inlined include. Index 0 is the top-level source — left empty because the resolver is handed only the source text and its directory, not the top-level file's path, so the caller (which knows which file it asked to expand) fills index 0. Consumers map a glslang / driver diagnostic of the form <i>:<line> back to <path>:<line>.
Returns
Expanded source, or empty string on error

Member Data Documentation

◆ GeneratedPreambleInclude

const char* PhosphorShaders::ShaderIncludeResolver::GeneratedPreambleInclude = "p_generated.glsl"
staticconstexpr

Reserved include name for the generated p_<id> autocomplete sidecar (plasmazones-shader-validate --emit-preamble).

An #include of a file with this basename is skipped (treated as a no-op) during expansion: the real param preamble is spliced at load, so the sidecar is an editor-only aid that must neither resolve nor error at runtime. Lets an author keep #include "p_generated.glsl" in the frag for glslls autocomplete while shipping it unchanged, with or without the sidecar present.

◆ MaxExpandedSize

qsizetype PhosphorShaders::ShaderIncludeResolver::MaxExpandedSize = 16 << 20
staticconstexpr

Largest expanded source, in UTF-16 code units.

One file may include another several times at each of the MaxIncludeDepth levels, so the depth and the per-file limit alone do not bound the output.

◆ MaxIncludeBytes

qint64 PhosphorShaders::ShaderIncludeResolver::MaxIncludeBytes = 1 << 20
staticconstexpr

Largest include file, in bytes.

A bigger file is an error, not a truncated read.

◆ MaxIncludeDepth

int PhosphorShaders::ShaderIncludeResolver::MaxIncludeDepth = 10
staticconstexpr

The documentation for this class was generated from the following file: