PhosphorShaders::ShaderRegistry Class Reference

Registry of available shader effects. More...

#include <phosphor-shaders/include/PhosphorShaders/ShaderRegistry.h>

Inheritance diagram for PhosphorShaders::ShaderRegistry:

Classes
struct	ParameterInfo
struct	ShaderInfo
class	ShaderPack
	Registry entry: a discovered shader as a PhosphorRegistry factory. More...

Signals
void	shadersChanged ()
void	shaderCompilationStarted (const QString &shaderId)
void	shaderCompilationFinished (const QString &shaderId, bool success, const QString &error)

Public Member Functions
	ShaderRegistry (QObject *parent=nullptr)
	~ShaderRegistry () override
void	addSearchPath (const QString &path, PhosphorFsLoader::LiveReload liveReload=PhosphorFsLoader::LiveReload::On)
void	addSearchPaths (const QStringList &paths, PhosphorFsLoader::LiveReload liveReload=PhosphorFsLoader::LiveReload::On, PhosphorFsLoader::RegistrationOrder order=PhosphorFsLoader::RegistrationOrder::LowestPriorityFirst)
QStringList	searchPaths () const
void	setUserPath (const QString &path)
void	refresh ()
QList< ShaderInfo >	availableShaders () const
QVariantList	availableShadersVariant () const
ShaderInfo	shader (const QString &id) const
QVariantMap	shaderInfo (const QString &id) const
QUrl	shaderUrl (const QString &id) const
QVariantMap	defaultParams (const QString &id) const
bool	validateParams (const QString &id, const QVariantMap &params) const
QVariantMap	validateAndCoerceParams (const QString &id, const QVariantMap &params) const
QVariantMap	translateParamsToUniforms (const QString &shaderId, const QVariantMap &storedParams) const
QVariantMap	presetParams (const QString &shaderId, const QString &presetName) const
QStringList	shaderPresetNames (const QString &shaderId) const
QVariantList	shaderPresetsVariant (const QString &shaderId) const
bool	shadersEnabled () const
	Always true — once a ShaderRegistry is constructed, shader discovery and metadata are functional (the registry is purely a metadata-pack walker; actual shader compilation lives in the phosphor-rendering library which carries the Qt6::ShaderTools dependency).
void	reportShaderBakeStarted (const QString &shaderId)
void	reportShaderBakeFinished (const QString &shaderId, bool success, const QString &error)

Static Public Member Functions
static QString	noneShaderUuid ()
static bool	isNoneShader (const QString &id)
static QString	paramPreamble (const ShaderInfo &info)
	Build the generated #define p_<id> <glsl-accessor> preamble (T1.1) for info's declared parameters, so a zone shader author reads a parameter by name (p_borderRadius) instead of hand-decoding a customParams[N].xyzw lane.
static ShaderInfo	parsePackMetadata (const QString &packDir, QString *error=nullptr)
	Parse a pack directory's metadata.json into a ShaderInfo using the SAME parser the live registry uses (T1.1 auto-slot assignment included), so an offline validator (phosphor-shader-validate) and the daemon agree on what a pack is.
static QString	wallpaperPath ()
static QImage	loadWallpaperImage ()
static QImage	loadWallpaperImage (const QRect &subGeom, const QRect &physGeom)
	Return the wallpaper image cropped to the portion that a sub-region (subGeom) occupies on a physical screen (physGeom), assuming "cover" scaling (aspect-correct fill, centered, overflow cropped) — the same placement model the wallpaperUv GLSL helper uses.
static QRect	computeWallpaperCropRect (QSize wpSize, const QRect &physGeom, const QRect &subGeom)
	Pure geometry helper: compute the pixel rect inside a wallpaper of size wpSize that corresponds to subGeom when the wallpaper covers physGeom under the same "cover" placement used by wallpaperUv.
static void	invalidateWallpaperCache ()

Detailed Description

Registry of available shader effects.

Discovers shaders from configured search paths, validates metadata, manages parameter presets, and watches for file changes.

Composition roots own a per-process instance and register search paths explicitly — there is no library-level singleton. Tests construct a per-fixture registry; downstream consumers (Phosphor shell, future plugin compositors) instantiate their own.

Storage + change-notify is the generic PhosphorRegistry::Registry<ShaderPack> (one ShaderPack wraps one discovered ShaderInfo); the on-disk scan + hot-reload is a PhosphorRegistry::MetadataPackLoader<ShaderPack> that parses each pack's metadata.json and reconciles the registry. Search-path management (addSearchPath, addSearchPaths, searchPaths, setUserPath, refresh) forwards to that loader.

Thread safety

GUI-thread only for both reads and mutations. The shader map lives inside the registry and is rebuilt on the GUI thread inside the rescan; the public lookup methods (availableShaders, shader, shaderInfo, shaderUrl) read it without synchronisation.

searchPaths() is the one exception: it returns a by-value snapshot of an implicitly-shared QStringList, so a GUI-thread caller can snapshot it and propagate the result to worker threads (this is the shader-warming path's contract). Calling searchPaths() from a worker thread concurrently with a GUI-thread mutation is a data race; snapshot on the GUI thread first.

Constructor & Destructor Documentation

ShaderRegistry()

PhosphorShaders::ShaderRegistry::ShaderRegistry ( QObject *  parent = nullptr )

explicit

~ShaderRegistry()

PhosphorShaders::ShaderRegistry::~ShaderRegistry ( )

override

Member Function Documentation

addSearchPath()

void PhosphorShaders::ShaderRegistry::addSearchPath	(	const QString &	path,
		PhosphorFsLoader::LiveReload	liveReload = PhosphorFsLoader::LiveReload::On
	)

addSearchPaths()

void PhosphorShaders::ShaderRegistry::addSearchPaths	(	const QStringList &	paths,
		PhosphorFsLoader::LiveReload	liveReload = PhosphorFsLoader::LiveReload::On,
		PhosphorFsLoader::RegistrationOrder	order = PhosphorFsLoader::RegistrationOrder::LowestPriorityFirst
	)

availableShaders()

QList< ShaderInfo > PhosphorShaders::ShaderRegistry::availableShaders

(

)

const

availableShadersVariant()

QVariantList PhosphorShaders::ShaderRegistry::availableShadersVariant

(

)

const

computeWallpaperCropRect()

static QRect PhosphorShaders::ShaderRegistry::computeWallpaperCropRect ( QSize  wpSize, const QRect &  physGeom, const QRect &  subGeom  )

static

Pure geometry helper: compute the pixel rect inside a wallpaper of size wpSize that corresponds to subGeom when the wallpaper covers physGeom under the same "cover" placement used by wallpaperUv.

Returns an invalid rect if inputs are degenerate or if subGeom fully covers physGeom (caller should use the full image in that case). Exposed for unit testing.

defaultParams()

QVariantMap PhosphorShaders::ShaderRegistry::defaultParams

(

const QString &

id

)

const

invalidateWallpaperCache()

static void PhosphorShaders::ShaderRegistry::invalidateWallpaperCache ( )

static

isNoneShader()

static bool PhosphorShaders::ShaderRegistry::isNoneShader ( const QString &  id )

static

loadWallpaperImage() [1/2]

static QImage PhosphorShaders::ShaderRegistry::loadWallpaperImage ( )

static

loadWallpaperImage() [2/2]

static QImage PhosphorShaders::ShaderRegistry::loadWallpaperImage ( const QRect &  subGeom, const QRect &  physGeom  )

static

Return the wallpaper image cropped to the portion that a sub-region (subGeom) occupies on a physical screen (physGeom), assuming "cover" scaling (aspect-correct fill, centered, overflow cropped) — the same placement model the wallpaperUv GLSL helper uses.

Returns the full (uncropped) wallpaper when either rect is invalid or when subGeom covers all of physGeom.

Virtual screens that share a physical monitor need this so each VS samples the wallpaper portion it occupies on the monitor, instead of each getting the center-cropped wallpaper as if it were a full screen.

The result is memoized keyed on (subGeom, physGeom, wallpaper mtime), so repeated calls for the same VS return the same QImage (stable cacheKey()) and avoid re-uploading to the GPU each frame.

noneShaderUuid()

static QString PhosphorShaders::ShaderRegistry::noneShaderUuid ( )

static

paramPreamble()

static QString PhosphorShaders::ShaderRegistry::paramPreamble ( const ShaderInfo &  info )

static

Build the generated #define p_<id> <glsl-accessor> preamble (T1.1) for info's declared parameters, so a zone shader author reads a parameter by name (p_borderRadius) instead of hand-decoding a customParams[N].xyzw lane.

Each param's explicit slot drives the accessor exactly as ParameterInfo::uniformName() / translateParamsToUniforms derive the upload target — scalar slot N → customParams[N/4].<xyzw>, color slot N → customColors[N], image slot N → uTexture<N> — so the macro a shader reads resolves to the same UBO lane the value is uploaded to. The daemon overlay splices the result after the shader's #version (via PhosphorShaders::spliceAfterVersion). Empty when the shader declares no parameters.

parsePackMetadata()

static ShaderInfo PhosphorShaders::ShaderRegistry::parsePackMetadata ( const QString &  packDir, QString *  error = nullptr  )

static

Parse a pack directory's metadata.json into a ShaderInfo using the SAME parser the live registry uses (T1.1 auto-slot assignment included), so an offline validator (phosphor-shader-validate) and the daemon agree on what a pack is.

Returns an invalid ShaderInfo and sets error on a missing/unreadable file or non-object JSON root. Does NOT verify that the frag/buffer files exist on disk — that's a validator lint, not a parse failure — so sourcePath/bufferShaderPaths are returned as declared.

presetParams()

QVariantMap PhosphorShaders::ShaderRegistry::presetParams	(	const QString &	shaderId,
		const QString &	presetName
	)		const

refresh()

void PhosphorShaders::ShaderRegistry::refresh

(

)

reportShaderBakeFinished()

void PhosphorShaders::ShaderRegistry::reportShaderBakeFinished	(	const QString &	shaderId,
		bool	success,
		const QString &	error
	)

reportShaderBakeStarted()

void PhosphorShaders::ShaderRegistry::reportShaderBakeStarted

(

const QString &

shaderId

)

searchPaths()

QStringList PhosphorShaders::ShaderRegistry::searchPaths

(

)

const

setUserPath()

void PhosphorShaders::ShaderRegistry::setUserPath

(

const QString &

path

)

shader()

ShaderInfo PhosphorShaders::ShaderRegistry::shader

(

const QString &

id

)

const

shaderCompilationFinished

void PhosphorShaders::ShaderRegistry::shaderCompilationFinished ( const QString &  shaderId, bool  success, const QString &  error  )

signal

shaderCompilationStarted

void PhosphorShaders::ShaderRegistry::shaderCompilationStarted ( const QString &  shaderId )

signal

shaderInfo()

QVariantMap PhosphorShaders::ShaderRegistry::shaderInfo

(

const QString &

id

)

const

shaderPresetNames()

QStringList PhosphorShaders::ShaderRegistry::shaderPresetNames

(

const QString &

shaderId

)

const

shaderPresetsVariant()

QVariantList PhosphorShaders::ShaderRegistry::shaderPresetsVariant

(

const QString &

shaderId

)

const

shadersChanged

void PhosphorShaders::ShaderRegistry::shadersChanged ( )

signal

shadersEnabled()

bool PhosphorShaders::ShaderRegistry::shadersEnabled ( ) const

inline

Always true — once a ShaderRegistry is constructed, shader discovery and metadata are functional (the registry is purely a metadata-pack walker; actual shader compilation lives in the phosphor-rendering library which carries the Qt6::ShaderTools dependency).

Kept as Q_INVOKABLE because QML callers historically used it as a feature gate from the era when the build had an opt-out for shader support; new code can omit the check.

shaderUrl()

QUrl PhosphorShaders::ShaderRegistry::shaderUrl

(

const QString &

id

)

const

translateParamsToUniforms()

QVariantMap PhosphorShaders::ShaderRegistry::translateParamsToUniforms	(	const QString &	shaderId,
		const QVariantMap &	storedParams
	)		const

validateAndCoerceParams()

QVariantMap PhosphorShaders::ShaderRegistry::validateAndCoerceParams	(	const QString &	id,
		const QVariantMap &	params
	)		const

validateParams()

bool PhosphorShaders::ShaderRegistry::validateParams	(	const QString &	id,
		const QVariantMap &	params
	)		const

wallpaperPath()

static QString PhosphorShaders::ShaderRegistry::wallpaperPath ( )

static

---

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

• phosphor-shaders/include/PhosphorShaders/ShaderRegistry.h