GLShader

A GskGLShader is a snippet of GLSL that is meant to run in the fragment shader of the rendering pipeline.

A fragment shader gets the coordinates being rendered as input and produces the pixel values for that particular pixel. Additionally, the shader can declare a set of other input arguments, called uniforms (as they are uniform over all the calls to your shader in each instance of use). A shader can also receive up to 4 textures that it can use as input when producing the pixel data.

GskGLShader is usually used with gtk_snapshot_push_gl_shader() to produce a [class@Gsk.GLShaderNode] in the rendering hierarchy, and then its input textures are constructed by rendering the child nodes to textures before rendering the shader node itself. (You can pass texture nodes as children if you want to directly use a texture as input).

The actual shader code is GLSL code that gets combined with some other code into the fragment shader. Since the exact capabilities of the GPU driver differs between different OpenGL drivers and hardware, GTK adds some defines that you can use to ensure your GLSL code runs on as many drivers as it can.

If the OpenGL driver is GLES, then the shader language version is set to 100, and GSK_GLES will be defined in the shader.

Otherwise, if the OpenGL driver does not support the 3.2 core profile, then the shader will run with language version 110 for GL2 and 130 for GL3, and GSK_LEGACY will be defined in the shader.

If the OpenGL driver supports the 3.2 code profile, it will be used, the shader language version is set to 150, and GSK_GL3 will be defined in the shader.

The main function the shader must implement is:

void mainImage(out vec4 fragColor,
in vec2 fragCoord,
in vec2 resolution,
in vec2 uv)

Where the input @fragCoord is the coordinate of the pixel we're currently rendering, relative to the boundary rectangle that was specified in the GskGLShaderNode, and @resolution is the width and height of that rectangle. This is in the typical GTK coordinate system with the origin in the top left. @uv contains the u and v coordinates that can be used to index a texture at the corresponding point. These coordinates are in the [0..1]x[0..1] region, with 0, 0 being in the lower left corder (which is typical for OpenGL).

The output @fragColor should be a RGBA color (with premultiplied alpha) that will be used as the output for the specified pixel location. Note that this output will be automatically clipped to the clip region of the glshader node.

In addition to the function arguments the shader can define up to 4 uniforms for textures which must be called u_textureN (i.e. u_texture1 to u_texture4) as well as any custom uniforms you want of types int, uint, bool, float, vec2, vec3 or vec4.

All textures sources contain premultiplied alpha colors, but if some there are outer sources of colors there is a gsk_premultiply() helper to compute premultiplication when needed.

Note that GTK parses the uniform declarations, so each uniform has to be on a line by itself with no other code, like so:

uniform float u_time;
uniform vec3 u_color;
uniform sampler2D u_texture1;
uniform sampler2D u_texture2;

GTK uses the the "gsk" namespace in the symbols it uses in the shader, so your code should not use any symbols with the prefix gsk or GSK. There are some helper functions declared that you can use:

vec4 GskTexture(sampler2D sampler, vec2 texCoords);

This samples a texture (e.g. u_texture1) at the specified coordinates, and containes some helper ifdefs to ensure that it works on all OpenGL versions.

You can compile the shader yourself using [method@Gsk.GLShader.compile], otherwise the GSK renderer will do it when it handling the glshader node. If errors occurs, the returned @error will include the glsl sources, so you can see what GSK was passing to the compiler. You can also set GSK_DEBUG=shaders in the environment to see the sources and other relevant information about all shaders that GSK is handling.

An example shader

uniform float position;
uniform sampler2D u_texture1;
uniform sampler2D u_texture2;

void mainImage(out vec4 fragColor,
in vec2 fragCoord,
in vec2 resolution,
in vec2 uv) {
vec4 source1 = GskTexture(u_texture1, uv);
vec4 source2 = GskTexture(u_texture2, uv);

fragColor = position * source1 + (1.0 - position) * source2;
}

class GLShader : ObjectG {

protected

GskGLShader* gskGLShader;

GskGLShader* getGLShaderStruct(bool transferOwnership);

void* getStruct();

this(GskGLShader* gskGLShader, bool ownedRef);

static GType getType();

this(Bytes sourcecode);

this(string resourcePath);

bool compile(Renderer renderer);

int findUniformByName(string name);

Bytes formatArgsVa(void* uniforms);

bool getArgBool(Bytes args, int idx);

float getArgFloat(Bytes args, int idx);

int getArgInt(Bytes args, int idx);

uint getArgUint(Bytes args, int idx);

void getArgVec2(Bytes args, int idx, Vec2 outValue);

void getArgVec3(Bytes args, int idx, Vec3 outValue);

void getArgVec4(Bytes args, int idx, Vec4 outValue);

size_t getArgsSize();

int getNTextures();

int getNUniforms();

string getResource();

Bytes getSource();

string getUniformName(int idx);

int getUniformOffset(int idx);

GskGLUniformType getUniformType(int idx);

}

Constructors

this this(GskGLShader* gskGLShader, bool ownedRef): Sets our main struct and passes it to the parent class.
this this(Bytes sourcecode): Creates a GskGLShader that will render pixels using the specified code.
this this(string resourcePath): Creates a GskGLShader that will render pixels using the specified code.

Members

Functions

compile bool compile(Renderer renderer): Tries to compile the @shader for the given @renderer.
findUniformByName int findUniformByName(string name): Looks for a uniform by the name @name, and returns the index of the uniform, or -1 if it was not found.
formatArgsVa Bytes formatArgsVa(void* uniforms): Formats the uniform data as needed for feeding the named uniforms values into the shader.
getArgBool bool getArgBool(Bytes args, int idx): Gets the value of the uniform @idx in the @args block.
getArgFloat float getArgFloat(Bytes args, int idx): Gets the value of the uniform @idx in the @args block.
getArgInt int getArgInt(Bytes args, int idx): Gets the value of the uniform @idx in the @args block.
getArgUint uint getArgUint(Bytes args, int idx): Gets the value of the uniform @idx in the @args block.
getArgVec2 void getArgVec2(Bytes args, int idx, Vec2 outValue): Gets the value of the uniform @idx in the @args block.
getArgVec3 void getArgVec3(Bytes args, int idx, Vec3 outValue): Gets the value of the uniform @idx in the @args block.
getArgVec4 void getArgVec4(Bytes args, int idx, Vec4 outValue): Gets the value of the uniform @idx in the @args block.
getArgsSize size_t getArgsSize(): Get the size of the data block used to specify arguments for this shader.
getGLShaderStruct GskGLShader* getGLShaderStruct(bool transferOwnership): Get the main Gtk struct
getNTextures int getNTextures(): Returns the number of textures that the shader requires.
getNUniforms int getNUniforms(): Get the number of declared uniforms for this shader.
getResource string getResource(): Gets the resource path for the GLSL sourcecode being used to render this shader.
getSource Bytes getSource(): Gets the GLSL sourcecode being used to render this shader.
getStruct void* getStruct(): the main Gtk struct as a void*
getUniformName string getUniformName(int idx): Get the name of the declared uniform for this shader at index @idx.
getUniformOffset int getUniformOffset(int idx): Get the offset into the data block where data for this uniforms is stored.
getUniformType GskGLUniformType getUniformType(int idx): Get the type of the declared uniform for this shader at index @idx.

Static functions

getType GType getType()

Variables

gskGLShader GskGLShader* gskGLShader;: the main Gtk struct

Inherited Members

From ObjectG

gObject GObject* gObject;: the main Gtk struct
ownedRef bool ownedRef;: Undocumented in source.
getObjectGStruct GObject* getObjectGStruct(bool transferOwnership): Get the main Gtk struct
getStruct void* getStruct(): the main Gtk struct as a void*
isGcRoot bool isGcRoot;: Undocumented in source.
signals DClosure[gulong] signals;: Undocumented in source.
destroyNotify void destroyNotify(ObjectG obj): Undocumented in source. Be warned that the author may not have intended to support it.
toggleNotify void toggleNotify(ObjectG obj, GObject* object, int isLastRef): Undocumented in source. Be warned that the author may not have intended to support it.
~this ~this(): Undocumented in source.
opCast T opCast()
getDObject RT getDObject(U obj, bool ownedRef): Gets a D Object from the objects table of associations.
removeGcRoot void removeGcRoot(): Undocumented in source. Be warned that the author may not have intended to support it.
setProperty void setProperty(string propertyName, T value)
unref deprecated void unref(ObjectG obj): Undocumented in source. Be warned that the author may not have intended to support it.
doref deprecated ObjectG doref(ObjectG obj): Undocumented in source. Be warned that the author may not have intended to support it.
addOnNotify gulong addOnNotify(void delegate(ParamSpec, ObjectG) dlg, string property, ConnectFlags connectFlags): The notify signal is emitted on an object when one of its properties has been changed. Note that getting this signal doesn't guarantee that the value of the property has actually changed, it may also be emitted when the setter for the property is called to reinstate the previous value.
getType GType getType()
compatControl size_t compatControl(size_t what, void* data)
interfaceFindProperty ParamSpec interfaceFindProperty(TypeInterface gIface, string propertyName): Find the #GParamSpec with the given name for an interface. Generally, the interface vtable passed in as @g_iface will be the default vtable from g_type_default_interface_ref(), or, if you know the interface has already been loaded, g_type_default_interface_peek().
interfaceInstallProperty void interfaceInstallProperty(TypeInterface gIface, ParamSpec pspec): Add a property to an interface; this is only useful for interfaces that are added to GObject-derived types. Adding a property to an interface forces all objects classes with that interface to have a compatible property. The compatible property could be a newly created #GParamSpec, but normally g_object_class_override_property() will be used so that the object class only needs to provide an implementation and inherits the property description, default value, bounds, and so forth from the interface property.
interfaceListProperties ParamSpec[] interfaceListProperties(TypeInterface gIface): Lists the properties of an interface.Generally, the interface vtable passed in as @g_iface will be the default vtable from g_type_default_interface_ref(), or, if you know the interface has already been loaded, g_type_default_interface_peek().
addToggleRef void addToggleRef(GToggleNotify notify, void* data): Increases the reference count of the object by one and sets a callback to be called when all other references to the object are dropped, or when this is already the last reference to the object and another reference is established.
addWeakPointer void addWeakPointer(void* weakPointerLocation): Adds a weak reference from weak_pointer to @object to indicate that the pointer located at @weak_pointer_location is only valid during the lifetime of @object. When the @object is finalized, @weak_pointer will be set to %NULL.
bindProperty Binding bindProperty(string sourceProperty, ObjectG target, string targetProperty, GBindingFlags flags): Creates a binding between @source_property on @source and @target_property on @target. Whenever the @source_property is changed the @target_property is updated using the same value. For instance:
bindPropertyFull Binding bindPropertyFull(string sourceProperty, ObjectG target, string targetProperty, GBindingFlags flags, GBindingTransformFunc transformTo, GBindingTransformFunc transformFrom, void* userData, GDestroyNotify notify): Complete version of g_object_bind_property().
bindPropertyWithClosures Binding bindPropertyWithClosures(string sourceProperty, ObjectG target, string targetProperty, GBindingFlags flags, Closure transformTo, Closure transformFrom): Creates a binding between @source_property on @source and @target_property on @target, allowing you to set the transformation functions to be used by the binding.
dupData void* dupData(string key, GDuplicateFunc dupFunc, void* userData): This is a variant of g_object_get_data() which returns a 'duplicate' of the value. @dup_func defines the meaning of 'duplicate' in this context, it could e.g. take a reference on a ref-counted object.
dupQdata void* dupQdata(GQuark quark, GDuplicateFunc dupFunc, void* userData): This is a variant of g_object_get_qdata() which returns a 'duplicate' of the value. @dup_func defines the meaning of 'duplicate' in this context, it could e.g. take a reference on a ref-counted object.
forceFloating void forceFloating(): This function is intended for #GObject implementations to re-enforce a floating[floating-ref] object reference. Doing this is seldom required: all #GInitiallyUnowneds are created with a floating reference which usually just needs to be sunken by calling g_object_ref_sink().
freezeNotify void freezeNotify(): Increases the freeze count on @object. If the freeze count is non-zero, the emission of "notify" signals on @object is stopped. The signals are queued until the freeze count is decreased to zero. Duplicate notifications are squashed so that at most one #GObject::notify signal is emitted for each property modified while the object is frozen.
getData void* getData(string key): Gets a named field from the objects table of associations (see g_object_set_data()).
getProperty void getProperty(string propertyName, Value value): Gets a property of an object.
getQdata void* getQdata(GQuark quark): This function gets back user data pointers stored via g_object_set_qdata().
getValist void getValist(string firstPropertyName, void* varArgs): Gets properties of an object.
getv void getv(string[] names, Value[] values): Gets @n_properties properties for an @object. Obtained properties will be set to @values. All properties must be valid. Warnings will be emitted and undefined behaviour may result if invalid properties are passed in.
isFloating bool isFloating(): Checks whether @object has a floating[floating-ref] reference.
notify void notify(string propertyName): Emits a "notify" signal for the property @property_name on @object.
notifyByPspec void notifyByPspec(ParamSpec pspec): Emits a "notify" signal for the property specified by @pspec on @object.
doref alias doref = ref_: Undocumented in source.
ref_ ObjectG ref_(): Increases the reference count of @object.
refSink ObjectG refSink(): Increase the reference count of @object, and possibly remove the floating[floating-ref] reference, if @object has a floating reference.
removeToggleRef void removeToggleRef(GToggleNotify notify, void* data): Removes a reference added with g_object_add_toggle_ref(). The reference count of the object is decreased by one.
removeWeakPointer void removeWeakPointer(void* weakPointerLocation): Removes a weak reference from @object that was previously added using g_object_add_weak_pointer(). The @weak_pointer_location has to match the one used with g_object_add_weak_pointer().
replaceData bool replaceData(string key, void* oldval, void* newval, GDestroyNotify destroy, GDestroyNotify oldDestroy): Compares the user data for the key @key on @object with @oldval, and if they are the same, replaces @oldval with @newval.
replaceQdata bool replaceQdata(GQuark quark, void* oldval, void* newval, GDestroyNotify destroy, GDestroyNotify oldDestroy): Compares the user data for the key @quark on @object with @oldval, and if they are the same, replaces @oldval with @newval.
runDispose void runDispose(): Releases all references to other objects. This can be used to break reference cycles.
setData void setData(string key, void* data): Each object carries around a table of associations from strings to pointers. This function lets you set an association.
setDataFull void setDataFull(string key, void* data, GDestroyNotify destroy): Like g_object_set_data() except it adds notification for when the association is destroyed, either by setting it to a different value or when the object is destroyed.
setProperty void setProperty(string propertyName, Value value): Sets a property on an object.
setQdata void setQdata(GQuark quark, void* data): This sets an opaque, named pointer on an object. The name is specified through a #GQuark (retrieved e.g. via g_quark_from_static_string()), and the pointer can be gotten back from the @object with g_object_get_qdata() until the @object is finalized. Setting a previously set user data pointer, overrides (frees) the old pointer set, using #NULL as pointer essentially removes the data stored.
setQdataFull void setQdataFull(GQuark quark, void* data, GDestroyNotify destroy): This function works like g_object_set_qdata(), but in addition, a void (*destroy) (gpointer) function may be specified which is called with @data as argument when the @object is finalized, or the data is being overwritten by a call to g_object_set_qdata() with the same @quark.
setValist void setValist(string firstPropertyName, void* varArgs): Sets properties on an object.
setv void setv(string[] names, Value[] values): Sets @n_properties properties for an @object. Properties to be set will be taken from @values. All properties must be valid. Warnings will be emitted and undefined behaviour may result if invalid properties are passed in.
stealData void* stealData(string key): Remove a specified datum from the object's data associations, without invoking the association's destroy handler.
stealQdata void* stealQdata(GQuark quark): This function gets back user data pointers stored via g_object_set_qdata() and removes the @data from object without invoking its destroy() function (if any was set). Usually, calling this function is only required to update user data pointers with a destroy notifier, for example: |[ void object_add_to_user_list (GObject *object, const gchar *new_string) { // the quark, naming the object data GQuark quark_string_list = g_quark_from_static_string ("my-string-list"); // retrieve the old string list GList *list = g_object_steal_qdata (object, quark_string_list);
thawNotify void thawNotify(): Reverts the effect of a previous call to g_object_freeze_notify(). The freeze count is decreased on @object and when it reaches zero, queued "notify" signals are emitted.
unref void unref(): Decreases the reference count of @object. When its reference count drops to 0, the object is finalized (i.e. its memory is freed).
watchClosure void watchClosure(Closure closure): This function essentially limits the life time of the @closure to the life time of the object. That is, when the object is finalized, the @closure is invalidated by calling g_closure_invalidate() on it, in order to prevent invocations of the closure with a finalized (nonexisting) object. Also, g_object_ref() and g_object_unref() are added as marshal guards to the @closure, to ensure that an extra reference count is held on @object during invocation of the @closure. Usually, this function will be called on closures that use this @object as closure data.
weakRef void weakRef(GWeakNotify notify, void* data): Adds a weak reference callback to an object. Weak references are used for notification when an object is disposed. They are called "weak references" because they allow you to safely hold a pointer to an object without calling g_object_ref() (g_object_ref() adds a strong reference, that is, forces the object to stay alive).
weakUnref void weakUnref(GWeakNotify notify, void* data): Removes a weak reference callback to an object.
clearObject void clearObject(ObjectG objectPtr): Clears a reference to a #GObject.