Interface to describe how an effect loader has to function. More...

#include <effectloader.h>

Inheritance diagram for KWin::AbstractEffectLoader:

Signals
void	effectLoaded (KWin::Effect *effect, const QString &name)
	The loader emits this signal when it successfully loaded an effect.

Public Member Functions
	~AbstractEffectLoader () override

virtual void	setConfig (KSharedConfig::Ptr config)
	The KSharedConfig this EffectLoader should operate on.

virtual bool	hasEffect (const QString &name) const =0
	Whether this Effect Loader can load the Effect with the given `name`.

virtual QStringList	listOfKnownEffects () const =0
	All the Effects this loader knows of.

virtual bool	loadEffect (const QString &name)=0
	Synchronous loading of the Effect with the given `name`.

virtual void	queryAndLoadAll ()=0
	The Effect Loader should query its store for all available effects and try to load them.

virtual bool	isEffectSupported (const QString &name) const =0
	Whether the Effect with the given `name` is supported by the compositing backend.

virtual void	clear ()=0
	Clears the load queue, that is all scheduled Effects are discarded from loading.

Protected Member Functions
	AbstractEffectLoader (QObject *parent=nullptr)

LoadEffectFlags	readConfig (const QString &effectName, bool defaultValue) const
	Checks the configuration for the Effect identified by `effectName`.

Detailed Description

Interface to describe how an effect loader has to function.

The AbstractEffectLoader specifies the methods a concrete loader has to implement and how those methods are expected to perform. Also it provides an interface to the outside world (that is EffectsHandler).

The abstraction is used because there are multiple types of Effects which need to be loaded:

Built-In Effects
Scripted Effects
Binary Plugin Effects

Serving all of them with one Effect Loader is rather complex given that different stores need to be queried at the same time. Thus the idea is to have one implementation per type and one implementation which makes use of all of them and combines the loading.

Definition at line 57 of file effectloader.h.

Constructor & Destructor Documentation

◆ ~AbstractEffectLoader()

KWin::AbstractEffectLoader::~AbstractEffectLoader ( )

override

Definition at line 43 of file effectloader.cpp.

◆ AbstractEffectLoader()

KWin::AbstractEffectLoader::AbstractEffectLoader ( QObject * parent = nullptr )

explicitprotected

Definition at line 38 of file effectloader.cpp.

Member Function Documentation

◆ clear()

virtual void KWin::AbstractEffectLoader::clear ( )

pure virtual

Clears the load queue, that is all scheduled Effects are discarded from loading.

Implemented in KWin::ScriptedEffectLoader, KWin::PluginEffectLoader, and KWin::EffectLoader.

◆ effectLoaded

void KWin::AbstractEffectLoader::effectLoaded	(	KWin::Effect *	effect,
		const QString &	name )

signal

The loader emits this signal when it successfully loaded an effect.

Parameters

effect	The created Effect
name	The internal name of the loaded Effect

Returns: void

◆ hasEffect()

virtual bool KWin::AbstractEffectLoader::hasEffect ( const QString & name ) const

pure virtual

Whether this Effect Loader can load the Effect with the given name.

The Effect Loader determines whether it knows or can find an Effect called name, and thus whether it can attempt to load the Effect.

Parameters

name	The name of the Effect to look for.

Returns: bool true if the Effect Loader knows this effect, false otherwise

Implemented in KWin::ScriptedEffectLoader, KWin::PluginEffectLoader, and KWin::EffectLoader.

◆ isEffectSupported()

virtual bool KWin::AbstractEffectLoader::isEffectSupported ( const QString & name ) const

pure virtual

Whether the Effect with the given name is supported by the compositing backend.

Parameters

name	The name of the Effect to check.

Returns: bool true if it is supported, false otherwise

Implemented in KWin::ScriptedEffectLoader, KWin::PluginEffectLoader, and KWin::EffectLoader.

◆ listOfKnownEffects()

virtual QStringList KWin::AbstractEffectLoader::listOfKnownEffects ( ) const

pure virtual

All the Effects this loader knows of.

The implementation should re-query its store whenever this method is invoked. It's possible that the store of effects changed (e.g. a new one got installed)

Returns: QStringList The internal names of the known Effects

Implemented in KWin::ScriptedEffectLoader, KWin::PluginEffectLoader, and KWin::EffectLoader.

◆ loadEffect()

virtual bool KWin::AbstractEffectLoader::loadEffect ( const QString & name )

pure virtual

Synchronous loading of the Effect with the given name.

Loads the Effect without checking any configuration value or any enabled by default function provided by the Effect.

The loader is expected to apply the following checks: If the Effect is already loaded, the Effect should not get loaded again. Thus the loader is expected to track which Effects it has loaded, and which of those have been destroyed. The loader should check whether the Effect is supported. If the Effect indicates it is not supported, it should not get loaded.

If the Effect loaded successfully the signal effectLoaded(KWin::Effect*,const QString&) must be emitted. Otherwise the user of the loader is not able to get the loaded Effect. It's not returning the Effect as queryAndLoadAll() is working async and thus the users of the loader are expected to be prepared for async loading.

Parameters

name	The internal name of the Effect which should be loaded

Returns: bool true if the effect could be loaded, false in error case

See also: queryAndLoadAll(); effectLoaded(KWin::Effect*,const QString&)

Implemented in KWin::ScriptedEffectLoader, KWin::PluginEffectLoader, and KWin::EffectLoader.

◆ queryAndLoadAll()

virtual void KWin::AbstractEffectLoader::queryAndLoadAll ( )

pure virtual

The Effect Loader should query its store for all available effects and try to load them.

The Effect Loader is supposed to perform this operation in a highly async way. If there is IO which needs to be performed this should be done in a background thread and a queue should be used to load the effects. The loader should make sure to not load more than one Effect in one event cycle. Loading the Effect has to be performed in the Compositor thread and thus blocks the Compositor. Therefore after loading one Effect all events should get processed first, so that the Compositor can perform a painting pass if needed. To simplify this operation one can use the EffectLoadQueue. This requires to add another loadEffect method with the custom loader specific type to refer to an Effect and LoadEffectFlags.

The LoadEffectFlags have to be determined by querying the configuration with readConfig(). If the Load flag is set the loading can proceed and all the checks from loadEffect(const QString &) have to be applied. In addition if the CheckDefaultFunction flag is set and the Effect provides such a method, it should be queried to determine whether the Effect is enabled by default. If such a method returns false the Effect should not get loaded. If the Effect does not provide a way to query whether it's enabled by default at runtime the flag can get ignored.

If the Effect loaded successfully the signal effectLoaded(KWin::Effect*,const QString&) must be emitted.

See also: loadEffect(const QString &); effectLoaded(KWin::Effect*,const QString&)

Implemented in KWin::ScriptedEffectLoader, KWin::PluginEffectLoader, and KWin::EffectLoader.

◆ readConfig()

LoadEffectFlags KWin::AbstractEffectLoader::readConfig	(	const QString &	effectName,
		bool	defaultValue ) const

protected

Checks the configuration for the Effect identified by effectName.

For each Effect there could be a key called "<effectName>Enabled". If there is such a key the returned flags will contain Load in case it's true. If the key does not exist the defaultValue determines whether the Effect should be loaded. A value of true means that Load | CheckDefaultFunction is returned, in case of false no Load flags are returned.

Parameters

effectName	The name of the Effect to look for in the configuration
defaultValue	Whether the Effect is enabled by default or not.

Returns: Flags indicating whether the Effect should be loaded and how it should be loaded

Definition at line 52 of file effectloader.cpp.

◆ setConfig()

void KWin::AbstractEffectLoader::setConfig ( KSharedConfig::Ptr config )

virtual

The KSharedConfig this EffectLoader should operate on.

Important: a valid KSharedConfig must be provided before trying to load any effects!

Parameters

config

Reimplemented in KWin::EffectLoader.

Definition at line 47 of file effectloader.cpp.

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

src/effect/effectloader.h
src/effect/effectloader.cpp

Signals

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~AbstractEffectLoader()

◆ AbstractEffectLoader()

Member Function Documentation

◆ clear()

◆ effectLoaded

◆ hasEffect()

◆ isEffectSupported()

◆ listOfKnownEffects()

◆ loadEffect()

◆ queryAndLoadAll()

◆ readConfig()

◆ setConfig()