API Documentation
Documentation for developing SailfishOS applicationsMaterial QML Type
A shader material definition for a Background item. More...
| Import Statement: | import Sailfish.Silica.Background 1.0 |
| Inherited By: |
Properties
- blending : bool
- fragmentShader : string
- patternSize : size
- vertexShader : string
- visible : bool
Detailed Description
Note: This QML type is under development and is subject to change.
A material provides a means of specifying a vertex and fragment shader and input variable combination which can be efficiently shared between multiple Background items. To use a Material it must be assigned to the material property of a Background.
The combination of a Background and Material is similar to a QtQuick ShaderEffect and can sometimes be used interchangeably with the primary difference being Background/Material has some specializations for item position independent display of a wallpaper image.
The vertexShader and fragmentShader properties allow the use of near standard GLSL shader programs to render the contents of a Background item. They are non-standard in that they ask you to define a backgroundMain() function instead of main(). Both shaders have some attributes they expect to be defined in the shader programs in order to pass data from the Background item.
Additional data may be passed from QML to a shader by defining a uniform attribute in the shader and a QML property in either the Background or Material with a compatible value with priority given to the Background properties.
| GLSL | QML property |
|---|---|
float |
|
vec2 |
|
vec3 |
|
vec4 |
|
sampler2D |
|
See also Material.
Property Documentation
Identifies if the material shader may blend with items behind it.
By default backgrounds are assumed to be opaque and this is false.
The GLSL fragment shader used to render a Background.
Material amends its own main() function to the shader to support minor variations in circumstances such has non-opaque Background items. To support this fragment shaders should define a backgroundMain() function this can call instead of their own main() function.
Two special shader uniforms can be defined in a material fragment shader which correspond to the the texture data of the sourceItem and patternItem proprties of Background. These are:
uniform lowp sampler2D sourceTexture; uniform lowp sampler2D patternTexture;
The values of any QML properties in a Background or Material definition will be used to populate a compatible uniform in the vertex shader.
Additionally the default vertex shader if used produces two varying attributes specifying the texture coordinates to sample those textures:
varying highp vec2 sourceCoord; varying highp vec2 patternCoord;
The default fragment shader which tiles a faint patternItem over the sourceItem is as follows:
uniform lowp sampler2D sourceTexture;
uniform lowp sampler2D patternTexture;
varying highp vec2 sourceCoord;
varying highp vec2 patternCoord;
void backgroundMain() {
lowp vec4 pattern = texture2D(patternTexture, patternCoord) * 0.1;
gl_FragColor = texture2D(sourceTexture, sourceCoord);
gl_FragColor = (gl_FragColor * (1.0 - pattern.a)) + pattern;
}Note that if the source or pattern items are unused by a material it is safe to omit the corresponding attributes.
Specifies a tiling size for the GLSL fragment shader uniform highp mat4 positionMatrix; transform.
If this is not set then the size is derived from the Background patternItem but this can be overridden for cases where there is no pattern item or a different size is wanted.
The GLSL vertex shader used to render a Background.
Material amends its own main() function to the shader to support minor variations in circumstances. To support this fragment shaders should define a backgroundMain() function this can call instead of their own main() function.
The input vertex coordinates of the vertex shader are suppled in an attribute named position;
attribute highp vec4 position;
Three special shader uniforms can be defined in a material vertex shader which correspond to the vertex position transform and the texture coordinate transforms of the sourceItem and patternItem properties of Background. These are:
uniform highp mat4 positionMatrix; uniform highp mat4 sourceMatrix; uniform highp mat4 patternMatrix;
The values of any QML properties in a Background or Material definition will be used to populate a compatible uniform in the vertex shader.
The default fragment shader if used expects two varying attributes specifying the texture coordinates to sample those textures:
varying highp vec2 sourceCoord; varying highp vec2 patternCoord;
The default vertex shader which tiles a patternItem over the sourceItem is as follows:
attribute highp vec4 position;
uniform highp mat4 positionMatrix;
uniform highp mat4 sourceMatrix;
uniform highp mat4 patternMatrix;
varying highp vec2 sourceCoord;
varying highp vec2 patternCoord;
void backgroundMain() {
gl_Position = positionMatrix * position;
sourceCoord = (sourceMatrix * gl_Position).xy;
patternCoord = (patternMatrix * gl_Position).xy;
}Note that if the source or pattern items are unused by a material it is safe to omit the corresponding attributes.
Whether there are any visible Background items utilizing the material.
This may be used to determine if any dynamic shader inputs like animations or sensors should be active.