 |
Qt
Internal/Contributor docs for the Qt SDK. Note: These are NOT official API docs; those are found at https://doc.qt.io/
|
|
Qt
Internal/Contributor docs for the Qt SDK. Note: These are NOT official API docs; those are found at https://doc.qt.io/
|
#include <qquick3deffect_p.h>
Public Member Functions | |
| QQuick3DEffect (QQuick3DObject *parent=nullptr) | |
| \qmlproperty list Effect::passes Contains a list of render \l {Pass}{passes} implemented by the effect. | |
| QQmlListProperty< QQuick3DShaderUtilsRenderPass > | passes () |
| void | effectChainDirty () |
| Public Member Functions inherited from QObject | |
| Q_INVOKABLE | QObject (QObject *parent=nullptr) |
| Constructs an object with parent object parent. | |
| virtual | ~QObject () |
| Destroys the object, deleting all its child objects. | |
| virtual bool | event (QEvent *event) |
| This virtual function receives events to an object and should return true if the event e was recognized and processed. | |
| virtual bool | eventFilter (QObject *watched, QEvent *event) |
| Filters events if this object has been installed as an event filter for the watched object. | |
| QString | objectName () const |
| Q_WEAK_OVERLOAD void | setObjectName (const QString &name) |
| Sets the object's name to name. | |
| void | setObjectName (QAnyStringView name) |
| This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. | |
| QBindable< QString > | bindableObjectName () |
| bool | isWidgetType () const |
Returns true if the object is a widget; otherwise returns false. | |
| bool | isWindowType () const |
Returns true if the object is a window; otherwise returns false. | |
| bool | isQuickItemType () const |
Returns true if the object is a QQuickItem; otherwise returns false. | |
| bool | isQmlObjectType () const |
| Returns whether the object has been created by the QML engine or ownership has been explicitly set via QJSEngine::setObjectOwnership(). | |
| bool | signalsBlocked () const noexcept |
Returns true if signals are blocked; otherwise returns false. | |
| bool | blockSignals (bool b) noexcept |
| If block is true, signals emitted by this object are blocked (i.e., emitting a signal will not invoke anything connected to it). | |
| QThread * | thread () const |
| Returns the thread in which the object lives. | |
| bool | moveToThread (QThread *thread QT6_DECL_NEW_OVERLOAD_TAIL) |
Changes the thread affinity for this object and its children and returns true on success. | |
| int | startTimer (int interval, Qt::TimerType timerType=Qt::CoarseTimer) |
| This is an overloaded function that will start a timer of type timerType and a timeout of interval milliseconds. | |
| int | startTimer (std::chrono::nanoseconds time, Qt::TimerType timerType=Qt::CoarseTimer) |
| void | killTimer (int id) |
| Kills the timer with timer identifier, id. | |
| void | killTimer (Qt::TimerId id) |
| template<typename T> | |
| T | findChild (QAnyStringView aName, Qt::FindChildOptions options=Qt::FindChildrenRecursively) const |
| Returns the child of this object that can be cast into type T and that is called name, or \nullptr if there is no such object. | |
| template<typename T> | |
| QList< T > | findChildren (QAnyStringView aName, Qt::FindChildOptions options=Qt::FindChildrenRecursively) const |
| Returns all children of this object with the given name that can be cast to type T, or an empty list if there are no such objects. | |
| template<typename T> | |
| T | findChild (Qt::FindChildOptions options=Qt::FindChildrenRecursively) const |
| This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. | |
| template<typename T> | |
| QList< T > | findChildren (Qt::FindChildOptions options=Qt::FindChildrenRecursively) const |
| This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. | |
| const QObjectList & | children () const |
| Returns a list of child objects. | |
| void | setParent (QObject *parent) |
| Makes the object a child of parent. | |
| void | installEventFilter (QObject *filterObj) |
| Installs an event filter filterObj on this object. | |
| void | removeEventFilter (QObject *obj) |
| Removes an event filter object obj from this object. | |
| QMetaObject::Connection | connect (const QObject *sender, const char *signal, const char *member, Qt::ConnectionType type=Qt::AutoConnection) const |
| bool | disconnect (const char *signal=nullptr, const QObject *receiver=nullptr, const char *member=nullptr) const |
| bool | disconnect (const QObject *receiver, const char *member=nullptr) const |
| void | dumpObjectTree () const |
| Dumps a tree of children to the debug output. | |
| void | dumpObjectInfo () const |
| Dumps information about signal connections, etc. | |
| bool | setProperty (const char *name, const QVariant &value) |
| Sets the value of the object's name property to value. | |
| bool | setProperty (const char *name, QVariant &&value) |
| QVariant | property (const char *name) const |
| Returns the value of the object's name property. | |
| QList< QByteArray > | dynamicPropertyNames () const |
| QBindingStorage * | bindingStorage () |
| const QBindingStorage * | bindingStorage () const |
| QObject * | parent () const |
| Returns a pointer to the parent object. | |
| bool | inherits (const char *classname) const |
Returns true if this object is an instance of a class that inherits className or a QObject subclass that inherits className; otherwise returns false. | |
| Public Member Functions inherited from QQmlParserStatus | |
| QQmlParserStatus () | |
| virtual | ~QQmlParserStatus () |
Protected Member Functions | |
| QSSGRenderGraphObject * | updateSpatialNode (QSSGRenderGraphObject *node) override |
| void | itemChange (QQuick3DObject::ItemChange, const QQuick3DObject::ItemChangeData &) override |
| Protected Member Functions inherited from QQuick3DObject | |
| virtual void | markAllDirty () |
| virtual void | itemChange (ItemChange, const ItemChangeData &) |
| QQuick3DObject (QQuick3DObjectPrivate &dd, QQuick3DObject *parent=nullptr) | |
| void | classBegin () override |
| Invoked after class creation, but before any properties have been set. | |
| void | componentComplete () override |
| Invoked after the root component that caused this instantiation has completed construction. | |
| bool | isComponentComplete () const |
| virtual void | preSync () |
| Protected Member Functions inherited from QObject | |
| QObject * | sender () const |
| Returns a pointer to the object that sent the signal, if called in a slot activated by a signal; otherwise it returns \nullptr. | |
| int | senderSignalIndex () const |
| int | receivers (const char *signal) const |
| Returns the number of receivers connected to the signal. | |
| bool | isSignalConnected (const QMetaMethod &signal) const |
| virtual void | timerEvent (QTimerEvent *event) |
| This event handler can be reimplemented in a subclass to receive timer events for the object. | |
| virtual void | childEvent (QChildEvent *event) |
| This event handler can be reimplemented in a subclass to receive child events. | |
| virtual void | customEvent (QEvent *event) |
| This event handler can be reimplemented in a subclass to receive custom events. | |
| virtual void | connectNotify (const QMetaMethod &signal) |
| virtual void | disconnectNotify (const QMetaMethod &signal) |
| QObject (QObjectPrivate &dd, QObject *parent=nullptr) | |
Properties | |
| QQmlListProperty< QQuick3DShaderUtilsRenderPass > | passes |
| Properties inherited from QQuick3DObject | |
| QQuick3DObject * | parent |
| \qmlproperty Object3D QtQuick3D::Object3D::parent This property holds the parent of the Object3D in a 3D scene. | |
| Properties inherited from QObject | |
| QString | objectName |
| the name of this object | |
Friends | |
| class | QQuick3DShaderUtilsTextureInput |
| class | QQuick3DSceneRenderer |
Additional Inherited Members | |
| Public Slots inherited from QQuick3DObject | |
| void | update () |
| void | setParentItem (QQuick3DObject *parentItem) |
| Public Slots inherited from QObject | |
| void | deleteLater () |
| \threadsafe | |
| Signals inherited from QQuick3DObject | |
| void | parentChanged () |
| void | childrenChanged () |
| void | stateChanged () |
| Signals inherited from QObject | |
| void | destroyed (QObject *=nullptr) |
| This signal is emitted immediately before the object obj is destroyed, after any instances of QPointer have been notified, and cannot be blocked. | |
| void | objectNameChanged (const QString &objectName, QPrivateSignal) |
| This signal is emitted after the object's name has been changed. | |
| Protected Attributes inherited from QObject | |
| QScopedPointer< QObjectData > | d_ptr |
| Related Symbols inherited from QObject | |
| template< class T > T | qobject_cast (const QObject *object) |
| Returns the given object cast to type T if the object is of type T (or of a subclass); otherwise returns \nullptr. | |
| template< typename T > T | qFindChildqFindChildren (const QObject *obj, const QString &name)() |
| template< typename T > QList< T > | qFindChildrenqFindChildren (const QObject *obj, const QString &name)() |
| QObjectList | |
| \macro Q_CLASSINFO(Name, Value) | |
Definition at line 32 of file qquick3deffect_p.h.
|
explicit |
\qmlproperty list Effect::passes Contains a list of render \l {Pass}{passes} implemented by the effect.
\qmltype Effect
\inherits Object3D
\inqmlmodule QtQuick3D
\nativetype QQuick3DEffect
\brief Base component for creating a post-processing effect.
The Effect type allows the user to implement their own post-processing
effects for QtQuick3D.
\section1 Post-processing effects
A post-processing effect is conceptually very similar to Qt Quick's \l
ShaderEffect item. When an effect is present, the scene is rendered into a
separate texture first. The effect is then applied by drawing a textured
quad to the main render target, depending on the
\l{View3D::renderMode}{render mode} of the View3D. The effect can provide a
vertex shader, a fragment shader, or both. Effects are always applied on the
entire scene, per View3D.
Effects are associated with the \l SceneEnvironment in the
\l{SceneEnvironment::effects} property. The property is a list: effects can
be chained together; they are applied in the order they are in the list,
using the previous step's output as the input to the next one, with the last
effect's output defining the contents of the View3D.
\note \l SceneEnvironment and \l ExtendedSceneEnvironment provide a set of
built-in effects, such as depth of field, glow/bloom, lens flare, color
grading, and vignette. Always consider first if these are sufficient for
the application's needs, and prefer using the built-in facilities instead
of implementing a custom post-processing effect.
Effects are similar to \l{CustomMaterial}{custom materials} in many
ways. However, a custom material is associated with a model and is
responsible for the shading of that given mesh. Whereas an effect's vertex
shader always gets a quad (for example, two triangles) as its input, while
its fragment shader samples the texture with the scene's content.
Unlike custom materials, effects support multiple passes. For many effects
this it not necessary, and when there is a need to apply multiple effects,
identical results can often be achieved by chaining together multiple
effects in \l{SceneEnvironment::effects}{the SceneEnvironment}. This is
demonstrated by the \l{Qt Quick 3D - Custom Effect Example}{Custom Effect
example} as well. However, passes have the possibility to request additional
color buffers (texture), and specify which of these additional buffers they
output to. This allows implementing more complex image processing techniques
since subsequent passes can then use one or more of these additional
buffers, plus the original scene's content, as their input. If necessary,
these additional buffers can have an extended lifetime, meaning their
content is preserved between frames, which allows implementing effects that
rely on accumulating content from multiple frames, such as, motion blur.
When compared to Qt Quick's 2D ShaderEffect, the 3D post-processing effects
have the advantage of being able to work with depth buffer data, as well as
the ability to implement multiple passes with intermediate buffers. In
addition, the texture-related capabilities are extended: Qt Quick 3D allows
more fine-grained control over filtering modes, and allows effects to work
with texture formats other than RGBA8, for example, floating point formats.
\note Post-processing effects are currently available when the View3D
has its \l{View3D::renderMode}{renderMode} set to \c Offscreen,
\c Underlay or \c Overlay. Effects will not be rendered for \c Inline mode.
\note When using post-processing effects, the application-provided shaders
should expect linear color data without tonemapping applied. The
tonemapping that is performed during the main render pass (or during skybox
rendering, if there is a skybox) when
\l{SceneEnvironment::tonemapMode}{tonemapMode} is set to a value other than
\c SceneEnvironment.TonemapModeNone, is automatically disabled when there
is at least one post-processing effect specified in the SceneEnvironment.
The last effect in the chain (more precisely, the last pass of the last
effect in the chain) will automatically get its fragment shader amended to
perform the same tonemapping the main render pass would.
\note Effects that perform their own tonemapping should be used in a
SceneEnvironment that has the built-in tonemapping disabled by setting
\l{SceneEnvironment::tonemapMode}{tonemapMode} to \c
SceneEnvironment.TonemapModeNone.
\note By default the texture used as the effects' input is created with a
floating point texture format, such as 16-bit floating point RGBA. The
output texture's format is the same since by default it follows the input
format. This can be overridden using \l Buffer and an empty name. The
default RGBA16F is useful because it allows working with non-tonemapped
linear data without having the color values outside the 0-1 range clamped.
\section1 Exposing data to the shaders
Like with CustomMaterial or ShaderEffect, the dynamic properties of an
Effect object can be changed and animated using the usual QML and Qt Quick
facilities, and the values are exposed to the shaders automatically. The
following list shows how properties are mapped:
\list
\li bool, int, real -> bool, int, float
\li QColor, \l{QtQml::Qt::rgba()}{color} -> vec4, and the color gets
converted to linear, assuming sRGB space for the color value specified in
QML. The built-in Qt colors, such as \c{"green"} are in sRGB color space as
well, and the same conversion is performed for all color properties of
DefaultMaterial and PrincipledMaterial, so this behavior of Effect
matches those.
\li QRect, QRectF, \l{QtQml::Qt::rect()}{rect} -> vec4
\li QPoint, QPointF, \l{QtQml::Qt::point()}{point}, QSize, QSizeF, \l{QtQml::Qt::size()}{size} -> vec2
\li QVector2D, \l{QtQml::Qt::vector2d()}{vector2d} -> vec3
\li QVector3D, \l{QtQml::Qt::vector3d()}{vector3d} -> vec3
\li QVector4D, \l{QtQml::Qt::vector4d()}{vector4d} -> vec4
\li QMatrix4x4, \l{QtQml::Qt::matrix4x4()}{matrix4x4} -> mat4
\li QQuaternion, \l{QtQml::Qt::quaternion()}{quaternion} -> vec4, scalar value is \c w
\li TextureInput -> sampler2D or samplerCube, depending on whether \l
Texture or \l CubeMapTexture is used in the texture property of the
TextureInput. Setting the \l{TextureInput::enabled}{enabled} property to
false leads to exposing a dummy texture to the shader, meaning the shaders
are still functional but will sample a texture with opaque black image
content. Pay attention to the fact that properties for samplers must always
reference a \l TextureInput object, not a \l Texture directly. When it
comes to the \l Texture properties, the source, tiling, and filtering
related ones are the only ones that are taken into account implicitly with
effects, as the rest (such as, UV transformations) is up to the custom
shaders to implement as they see fit.
\endlist
\note When a uniform referenced in the shader code does not have a
corresponding property, it will cause a shader compilation error when
processing the effect at run time. There are some exceptions to this,
such as, sampler uniforms, that get a dummy texture bound when no
corresponding QML property is present, but as a general rule, all uniforms
and samplers must have a corresponding property declared in the
Effect object.
\section1 Getting started with user-defined effects
A custom post-processing effect involves at minimum an Effect object and a
fragment shader snippet. Some effects will also want a customized vertex
shader as well.
As a simple example, let's create an effect that combines the scene's
content with an image, while further altering the red channel's value in an
animated manner:
\table 70%
\row
\li \qml
Effect {
id: simpleEffect
property TextureInput tex: TextureInput {
texture: Texture { source: "image.png" }
}
property real redLevel
NumberAnimation on redLevel { from: 0; to: 1; duration: 5000; loops: -1 }
passes: Pass {
shaders: Shader {
stage: Shader.Fragment
shader: "effect.frag"
}
}
}
\endqml
\li \badcode
void MAIN()
{
vec4 c = texture(tex, TEXTURE_UV);
c.r *= redLevel;
FRAGCOLOR = c * texture(INPUT, INPUT_UV);
}
\endcode
\endtable
Here the texture with the image \c{image.png} is exposed to the shader under
the name \c tex. The value of redLevel is available in the shader in a \c
float uniform with the same name.
The fragment shader must contain a function called \c MAIN. The final
fragment color is determined by \c FRAGCOLOR. The main input texture, with
the contents of the View3D's scene, is accessible under a \c sampler2D with
the name \c INPUT. The UV coordinates from the quad are in \c
INPUT_UV. These UV values are always suitable for sampling \c INPUT,
regardless of the underlying graphics API at run time (and so regardless of
the Y axis direction in images since the necessary adjustments are applied
automatically by Qt Quick 3D). Sampling the texture with our external image
is done using \c TEXTURE_UV. \c INPUT_UV is not suitable in cross-platform
applications since V needs to be flipped to cater for the coordinate system
differences mentioned before, using a logic that is different for textures
based on images and textures used as render targets. Fortunately this is all
taken care of by the engine so the shader need no further logic for this.
Once simpleEffect is available, it can be associated with the effects list
of a the View3D's SceneEnvironment:
\qml
environment: SceneEnvironment {
effects: [ simpleEffect ]
}
\endqml
The results would look something like the following, with the original scene
on the left and with the effect applied on the right:
\table 70%
\row
\li \image effect_intro_1.png
\li \image effect_intro_2.png
\endtable
\note The \c shader property value in Shader is a URL, as is the custom in
QML and Qt Quick, referencing the file containing the shader snippet, and
works very similarly to ShaderEffect or
\l{Image::source}{Image.source}. Only the \c file and \c qrc schemes are
supported.. It is also possible to omit the \c file scheme, allowing to
specify a relative path in a convenient way. Such a path is resolved
relative to the component's (the \c{.qml} file's) location.
\note Shader code is always provided using Vulkan-style GLSL, regardless of
the graphics API used by Qt at run time.
\note The vertex and fragment shader code provided by the effect are not
full, complete GLSL shaders on their own. Rather, they provide a \c MAIN
function, and optionally a set of \c VARYING declarations, which are then
amended with further shader code by the engine.
\note The above example is not compatible with the optional multiview rendering mode that is used in some VR/AR applications.
To make it function both with and without multiview mode, change MAIN() like this:
\badcode
void MAIN()
{
vec4 c = texture(tex, TEXTURE_UV);
c.r *= redLevel;
#if QSHADER_VIEW_COUNT >= 2
FRAGCOLOR = c * texture(INPUT, vec3(INPUT_UV, VIEW_INDEX));
#else
FRAGCOLOR = c * texture(INPUT, INPUT_UV);
#endif
}
\endcode
\section1 Effects with vertex shaders
A vertex shader, when present, must provide a function called \c MAIN. In
the vast majority of cases the custom vertex shader will not want to provide
its own calculation of the homogenous vertex position, but it is possible
using \c POSITION, \c VERTEX, and \c MODELVIEWPROJECTION_MATRIX. When
\c POSITION is not present in the custom shader code, a statement equivalent to
\c{POSITION = MODELVIEWPROJECTION_MATRIX * vec4(VERTEX, 1.0);} will be
injected automatically by Qt Quick 3D.
To pass data between the vertex and fragment shaders, use the VARYING
keyword. Internally this will then be transformed into the appropriate
vertex output or fragment input declaration. The fragment shader can use the
same declaration, which then allows to read the interpolated value for the
current fragment.
Let's look at example, that is in effect very similar to the built-in
DistortionSpiral effect:
\table 70%
\row
\li \badcode
VARYING vec2 center_vec;
void MAIN()
{
center_vec = INPUT_UV - vec2(0.5, 0.5);
center_vec.y *= INPUT_SIZE.y / INPUT_SIZE.x;
}
\endcode
\li \badcode
VARYING vec2 center_vec;
void MAIN()
{
float radius = 0.25;
float dist_to_center = length(center_vec) / radius;
vec2 texcoord = INPUT_UV;
if (dist_to_center <= 1.0) {
float rotation_amount = (1.0 - dist_to_center) * (1.0 - dist_to_center);
float r = radians(360.0) * rotation_amount / 4.0;
mat2 rotation = mat2(cos(r), sin(r), -sin(r), cos(r));
texcoord = vec2(0.5, 0.5) + rotation * (INPUT_UV - vec2(0.5, 0.5));
}
FRAGCOLOR = texture(INPUT, texcoord);
}
\endcode
\endtable
The Effect object's \c passes list should now specify both the vertex and
fragment snippets:
\qml
passes: Pass {
shaders: [
Shader {
stage: Shader.Vertex
shader: "effect.vert"
},
Shader {
stage: Shader.Fragment
shader: "effect.frag"
}
]
}
\endqml
The end result looks like the following:
\table 70%
\row
\li \image effect_intro_1.png
\li \image effect_intro_3.png
\endtable
\section1 Special keywords in effect shaders
\list
\li \c VARYING - Declares a vertex output or fragment input, depending on the type of the current shader.
\li \c MAIN - This function must always be present in an effect shader.
\li \c FRAGCOLOR - \c vec4 - The final fragment color; the output of the fragment shader. (fragment shader only)
\li \c POSITION - \c vec4 - The homogenous position calculated in the vertex shader. (vertex shader only)
\li \c MODELVIEWPROJECTION_MATRIX - \c mat4 - The transformation matrix for the screen quad.
\li \c VERTEX - \c vec3 - The vertices of the quad; the input to the vertex shader. (vertex shader only)
\li \c INPUT - \c sampler2D or \c sampler2DArray - The sampler for the input
texture with the scene rendered into it, unless a pass redirects its input
via a BufferInput object, in which case \c INPUT refers to the additional
color buffer's texture referenced by the BufferInput. With \l{Multiview
Rendering}{multiview rendering} enabled, which can be relevant for VR/AR
applications, this is a sampler2DArray, while the input texture becomes a 2D
texture array.
\li \c INPUT_UV - \c vec2 - UV coordinates for sampling \c INPUT.
\li \c TEXTURE_UV - \c vec2 - UV coordinates suitable for sampling a Texture
with contents loaded from an image file.
\li \c INPUT_SIZE - \c vec2 - The size of the \c INPUT texture, in pixels.
\li \c OUTPUT_SIZE - \c vec2 - The size of the output buffer, in
pixels. Often the same as \c INPUT_SIZE, unless the pass outputs to an extra
Buffer with a size multiplier on it.
\li \c FRAME - \c float - A frame counter, incremented after each frame in the View3D.
\li \c DEPTH_TEXTURE - \c sampler2D or \c sampler2DArray - A depth texture
with the depth buffer contents with the opaque objects in the scene. Like
with CustomMaterial, the presence of this keyword in the shader triggers
generating the depth texture automatically.
\li \c NORMAL_ROUGHNESS_TEXTURE - \c sampler2D - A texture with the
world-space normals and material roughness of the opaque objects in the
currently visible portion of the scene. Like with CustomMaterial, the
presence of this keyword in the shader implies an additional render pass to
generate the normal texture.
\li \c VIEW_INDEX - \c uint - With \l{Multiview Rendering}{multiview
rendering} enabled, this is the current view index, available in both vertex
and fragment shaders. Always 0 when multiview rendering is not used.
\li \c PROJECTION_MATRIX - \c mat4, the projection matrix. Note that with
\l{Multiview Rendering}{multiview rendering}, this is an array of matrices.
\li \c INVERSE_PROJECTION_MATRIX - \c mat4, the inverse projection matrix.
Note that with \l{Multiview Rendering}{multiview rendering}, this is an array
of matrices.
\li \c VIEW_MATRIX -> \c mat4, the view (camera) matrix.
Note that with \l{Multiview Rendering}{multiview rendering}, this is an array
of matrices.
\li float \c NDC_Y_UP - The value is \c 1 when the Y axis points up in
normalized device coordinate space, and \c{-1} when the Y axis points down.
Y pointing down is the case when rendering happens with Vulkan.
\li float \c FRAMEBUFFER_Y_UP - The value is \c 1 when the Y axis points up
in the coordinate system for framebuffers (textures), meaning \c{(0, 0)} is
the bottom-left corner. The value is \c{-1} when the Y axis points down,
\c{(0, 0)} being the top-left corner.
\li float \c NEAR_CLIP_VALUE - The value is \c -1 for when the clipping plane
range's starts at \c -1 and goes to \c 1. This is true when using OpenGL for
rendering. For other rendering backends the value of this property will be
\c 0 meaning the clipping plane range is \c 0 to \c 1.
\endlist
\section1 Building multi-pass effects
A multi-pass effect often uses more than one set of shaders, and takes the
\l{Pass::output}{output} and \l{Pass::commands}{commands} properties into
use. Each entry in the passes list translates to a render pass drawing a
quad into the pass's output texture, while sampling the effect's input texture
and optionally other textures as well.
The typical outline of a multi-pass Effect can look like the following:
\qml
passes: [
Pass {
shaders: [
Shader {
stage: Shader.Vertex
shader: "pass1.vert"
},
Shader {
stage: Shader.Fragment
shader: "pass1.frag"
}
This pass outputs to the intermediate texture described by the Buffer object. output: intermediateColorBuffer ], }, Pass { shaders: [ Shader { stage: Shader.Vertex shader: "pass2.vert" }, Shader { stage: Shader.Fragment shader: "pass2.frag" } The output of the last pass needs no redirection, it is the final result of the effect. ], commands: [ This pass reads from the intermediate texture, meaning INPUT in the shader will refer to the texture associated with the Buffer. BufferInput { buffer: intermediateColorBuffer } ] } ] \endqml
What is intermediateColorBuffer?
\qml Buffer { id: intermediateColorBuffer name: "tempBuffer" format: Buffer.RGBA8 textureFilterOperation: Buffer.Linear textureCoordOperation: Buffer.ClampToEdge } \endqml
The commented properties are not necessary if the desired values match the defaults.
Internally the presence of this Buffer object and referencing it from the output property of a Pass leads to creating a texture with a size matching the View3D, and so the size of the implicit input and output textures. When this is not desired, the \l{Buffer::sizeMultiplier}{sizeMultiplier} property can be used to get an intermediate texture with a different size. This can lead to the INPUT_SIZE and OUTPUT_SIZE uniforms in the shader having different values.
By default the Effect cannot count on textures preserving their contents between frames. When a new intermediate texture is created, it is cleared to {vec4(0.0)}. Afterwards, the same texture can be reused for another purpose. Therefore, effect passes should always write to the entire texture, without making assumptions about their content at the start of the pass. There is an exception to this: Buffer objects with \l{Buffer::bufferFlags}{bufferFlags} set to Buffer.SceneLifetime. This indicates that the texture is permanently associated with a pass of the effect and it will not be reused for other purposes. The contents of such color buffers is preserved between frames. This is typically used in a ping-pong fashion in effects like motion blur: the first pass takes the persistent buffer as its input, in addition to the effects main input texture, outputting to another intermediate buffer, while the second pass outputs to the persistent buffer. This way in the first frame the first pass samples an empty (transparent) texture, whereas in subsequent frames it samples the output of the second pass from the previous frame. A third pass can then blend the effect's input and the second pass' output together.
The BufferInput command type is used to expose custom texture buffers to the render pass.
For instance, to access someBuffer in the render pass shaders under the name, mySampler, the following can be added to its command list: \qml BufferInput { buffer: someBuffer; sampler: "mySampler" } \endqml
If the sampler name is not specified, INPUT will be used as default.
Buffers can be useful to share intermediate results between render passes.
To expose preloaded textures to the effect, TextureInput should be used instead. These can be defined as properties of the Effect itself, and will automatically be accessible to the shaders by their property names. \qml property TextureInput tex: TextureInput { texture: Texture { source: "image.png" } } \endqml
Here tex is a valid sampler in all shaders of all the passes of the effect.
When it comes to uniform values from properties, all passes in the Effect read the same values in their shaders. If necessary it is possible to override the value of a uniform just for a given pass. This is achieved by adding the \l SetUniformValue command to the list of commands for the pass.
Definition at line 632 of file qquick3deffect.cpp.
| void QQuick3DEffect::effectChainDirty | ( | ) |
Definition at line 1111 of file qquick3deffect.cpp.
|
overrideprotected |
Definition at line 1139 of file qquick3deffect.cpp.
| QQmlListProperty< QQuick3DShaderUtilsRenderPass > QQuick3DEffect::passes | ( | ) |
|
static |
Definition at line 1145 of file qquick3deffect.cpp.
|
static |
Definition at line 1157 of file qquick3deffect.cpp.
|
static |
Definition at line 1169 of file qquick3deffect.cpp.
|
static |
Definition at line 1163 of file qquick3deffect.cpp.
|
overrideprotectedvirtual |
Reimplemented from QQuick3DObject.
Definition at line 698 of file qquick3deffect.cpp.
|
friend |
Definition at line 64 of file qquick3deffect_p.h.
|
friend |
Definition at line 63 of file qquick3deffect_p.h.
|
read |
Definition at line 35 of file qquick3deffect_p.h.
1.14.0