yukijoou/kwin
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
kwin/src/scripting/documentation-effect-global.xml
Martin Flöser 7bececfa2f [scripting] Support shaders in scripted effects 
The scripting API is extended to support custom fragment shaders. To
support this a new method addFragmentShader is added taking ShaderTraits
and fragment shader. The GLShader is not exposed, instead a uint id is
provided which maps to the GLShader.

This shader id can be used in the animate and set calls to specify the
shader. The animation object is extended by the "fragmentShader" property.

The shader sources are located in the "shaders" directory of the package
contents.

E.g. the scale effect extended by the shader of the invert effect will
have the following layout:

   package/contents/
   -> code/
     -> main.js
   -> shaders/
     -> invert_core.frag
     -> invert.frag

The adjustment in code are:
 * in constructor to load the shader
    this.shader = effect.addFragmentShader(Effect.MapTexture, "invert.frag");
 * in animations objects of the slots the additions
   fragmentShader: this.shader
 * using the type Effect.Shader

or in full:

        window.scaleInAnimation = animate({
            window: window,
            curve: QEasingCurve.OutCubic,
            duration: this.duration,
            animations: [
                {
                    type: Effect.Scale,
                    from: this.inScale
                },
                {
                    type: Effect.Opacity,
                    from: 0
                },
                {
                    type: Effect.Shader,
                    fragmentShader: this.shader
                }
            ]
        });

The animation settings object supports a "uniform" value which takes the
string name of the uniform. For this uniform the location is resolved
and stored in the meta data of the AnimationEffect. This requires the
type Effect.ShaderUniform.

An example animation:

        window.scaleInAnimation = animate({
            window: window,
            curve: QEasingCurve.Linear,
            duration: this.duration,
            animations: [
                {
                    type: Effect.ShaderUniform,
                    fragmentShader: this.shader,
                    uniform: "uForOpening",
                    from: 1.0,
                    to: 1.0
                }
            ]
        });

Furthermore a new setUniform scriptable method is added to the
ScriptedEffect. This allows to update uniforms when the configuration
changes.

The call takes a generic QJSValue which supports:
 * float
 * array of 2, 3 or 4 components
 * string as color
 * variant as color

An example usage to read a color from the configuration and set it as a
uniform:

    effect.setUniform(this.shaderId,
                      "uEffectColor",
                      effect.readConfig("Color", "white"))
2022-05-04 15:19:47 +00:00

197 lines
11 KiB
XML
Raw Blame History

<?xml version='1.0' encoding='UTF-8' standalone='no'?>
<doxygen xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="compound.xsd" version="1.7.6.1">
<!-- Documentation for global KWin effect methods. In doxygen XML format as this can be converted to MediaWiki -->
<!-- Use script and XSLT from kde:scratch/graesslin/kwin-scripting-api-generator to generate the documentation -->
<!-- This xml is not meant to be doxygen complient -->
<compounddef>
<compoundname>Global</compoundname>
<briefdescription>Methods and properties added to the global JavaScript object.</briefdescription>
<sectiondef kind="property">
<memberdef kind="property" writable="no">
<type>KWin::EffectsHandler</type>
<definition></definition>
<argsstring></argsstring>
<name>effects</name>
<read></read>
<detaileddescription>Global property to the core wrapper of KWin Effects</detaileddescription>
</memberdef>
<memberdef kind="property" writable="no">
<type>KWin::ScriptedEffect</type>
<definition></definition>
<argsstring></argsstring>
<name>effect</name>
<read></read>
<detaileddescription>Global property to the actual Effect</detaileddescription>
</memberdef>
<memberdef kind="property" writable="no">
<type>object</type>
<definition></definition>
<argsstring></argsstring>
<name>Effect</name>
<read></read>
<detaileddescription>Provides access to enums defined in KWin::AnimationEffect and KWin::ScriptedEffect</detaileddescription>
</memberdef>
<memberdef kind="property" writable="no">
<type>object</type>
<definition></definition>
<argsstring></argsstring>
<name>KWin</name>
<read></read>
<detaileddescription>Provides access to enums defined in KWin::WorkspaceWrapper</detaileddescription>
</memberdef>
<memberdef kind="property" writable="no">
<type>object</type>
<definition></definition>
<argsstring></argsstring>
<name>QEasingCurve</name>
<read></read>
<detaileddescription>Provides access to enums defined in QEasingCurve</detaileddescription>
</memberdef>
</sectiondef>
<sectiondef kind="public-func">
<memberdef kind="function">
<type>Q_SCRIPTABLE QList&lt;quint64&gt;</type>
<definition>QList&lt;quint64&gt; KWin::ScriptedEffect::animate</definition>
<argsstring>(settings)</argsstring>
<name>animate</name>
<read></read>
<detaileddescription>
Schedules one or many animations for one window. The animations are defined through the settings object providing
a more declarative way to specify the animations than the animate call on the effect object. The settings object
supports the following attributes:
&lt;syntaxhighlight lang="javascript"&gt;
{
window: EffectWindow, /* the window to animate, required */
duration: int, /* duration in msec, required */
curve: QEasingCurve.Type, /* global easing curve, optional */
type: Effect.Attribute, /* for first animation, optional */
from: FPx2, /* for first animation, optional */
to: FPx2, /* for first animation, optional */
delay: int, /* for first animation, optional */
shader: int, /* for first animation, optional */
animations: [ /* additional animations, optional */
{
curve: QEasingCurve.Type, /* overrides global */
type: Effect.Attribute,
from: FPx2,
to: FPx2,
delay: int,
shader: int
}
]
}
&lt;/syntaxhighlight&gt;
At least one animation or attribute setter (see below) needs to be specified either with the top-level properties or in the animations list.
</detaileddescription>
</memberdef>
<memberdef kind="function">
<type>Q_SCRIPTABLE QList&lt;quint64&gt;</type>
<definition>QList&lt;quint64&gt; KWin::ScriptedEffect::set</definition>
<argsstring>(settings)</argsstring>
<name>set</name>
<read></read>
<detaileddescription>
Like animate, just that the manipulation does not implicitly end with the animation. You have to explicitly cancel it.
Until then, the manipulated attribute will remain at animation target value.
</detaileddescription>
</memberdef>
<memberdef kind="function">
<type>Q_SCRIPTABLE bool</type>
<definition>bool KWin::ScriptedEffect::cancel</definition>
<argsstring>(QList&lt;quint64&gt;)</argsstring>
<name>cancel</name>
<read></read>
<detaileddescription>
Cancel one or more present animations caused and returned by KWin::ScriptedEffect::animate or KWin::ScriptedEffect::set.
For convenience you can pass a single quint64 as well.
</detaileddescription>
</memberdef>
<memberdef kind="function">
<type>Q_SCRIPTABLE void</type>
<definition>void KWin::ScriptedEffect::print</definition>
<argsstring>(QVariant ... values)</argsstring>
<name>print</name>
<read></read>
<detaileddescription>Prints all provided values to kDebug and as a D-Bus signal</detaileddescription>
</memberdef>
<memberdef kind="function">
<type>Q_SCRIPTABLE int</type>
<definition>int KWin::ScriptedEffect::animationTime</definition>
<argsstring>(int duration)</argsstring>
<name>animationTime</name>
<read></read>
<detaileddescription>Adjusts the passed in duration to the global animation time facator.</detaileddescription>
</memberdef>
<memberdef kind="function">
<type>Q_SCRIPTABLE int</type>
<definition>int KWin::ScriptedEffect::displayWidth</definition>
<argsstring>()</argsstring>
<name>displayWidth</name>
<read></read>
<detaileddescription>Width of the complete display (all screens).</detaileddescription>
</memberdef>
<memberdef kind="function">
<type>Q_SCRIPTABLE int</type>
<definition>int KWin::ScriptedEffect::displayHeight</definition>
<argsstring>()</argsstring>
<name>displayHeight</name>
<read></read>
<detaileddescription>Height of the complete display (all screens).</detaileddescription>
</memberdef>
<memberdef kind="function">
<type>Q_SCRIPTABLE bool</type>
<definition>bool KWin::ScriptedEffect::registerScreenEdge</definition>
<argsstring>(ElectricBorder border, QScriptValue callback)</argsstring>
<name>registerScreenEdge</name>
<read></read>
<detaileddescription>Registers the callback for the screen edge. When the mouse gets pushed against the given edge the callback will be invoked.</detaileddescription>
</memberdef>
<memberdef kind="function">
<type>Q_SCRIPTABLE bool</type>
<definition>bool KWin::ScriptedEffect::registerShortcut</definition>
<argsstring>(QString title, QString text, QString keySequence, QScriptValue callback)</argsstring>
<name>registerShortcut</name>
<read></read>
<detaileddescription>Registers keySequence as a global shortcut. When the shortcut is invoked the callback will be called. Title and text are used to name the shortcut and make it available to the global shortcut configuration module.</detaileddescription>
</memberdef>
<memberdef kind="function">
<type>Q_SCRIPTABLE uint</type>
<definition>uint KWin::ScriptedEffect::addFragmentShader</definition>
<argsstring>(ShaderTrait traits, QString fragmentShaderFile)</argsstring>
<name>addFragmentShader</name>
<read></read>
<detaileddescription>Creates a shader and returns an identifier which can be used in animate or set. The shader sources must be provided in the shaders sub-directory of the contents package directory. The fragment shader needs to have the file extension frag. Each shader should be provided in a GLSL 1.10 and GLSL 1.40 variant. The 1.40 variant needs to have a suffix _core. E.g. there should be a shader myCustomShader.frag and myCustomShader_core.frag. The vertex shader is generated from the ShaderTrait. The ShaderTrait enum can be used as flags in this method.</detaileddescription>
</memberdef>
<memberdef kind="function">
<type>Q_SCRIPTABLE uint</type>
<definition>void KWin::ScriptedEffect::setUniform</definition>
<argsstring>(uint shaderId, QString name, QJSValue value)</argsstring>
<name>setUniform</name>
<read></read>
<detaileddescription>Updates the uniform value of the uniform identified by @p name for the shader identified by @p shaderId. The @p value can be a floating point numeric value (integer uniform values are not supported), an array with either 2, 3 or 4 numeric values, a string to identify a color or a variant value to identify a color as returned by readConfig. This method can be used to update the state of the shader when the configuration of the effect changed.</detaileddescription>
</memberdef>
</sectiondef>
</compounddef>
<compounddef>
<compoundname>KWin::FPx2</compoundname>
<briefdescription>This class is used to describe the animation end points, that is from which FPx2 values to which FPx2 values an animation goes. This class contains two properties to describe two animation components individually (e.g. width and height). But it's also possible to just have one value (e.g. opacity). In this case the definition of an FPx2 can be replaced by a single value.</briefdescription>
<sectiondef kind="property">
<memberdef kind="property" writable="yes">
<type>qreal</type>
<definition></definition>
<argsstring></argsstring>
<name>value1</name>
<read></read>
<detaileddescription></detaileddescription>
</memberdef>
<memberdef kind="property" writable="yes">
<type>qreal</type>
<definition></definition>
<argsstring></argsstring>
<name>value2</name>
<read></read>
<detaileddescription></detaileddescription>
</memberdef>
</sectiondef>
</compounddef>
</doxygen>
Reference in a new issue View git blame Copy permalink