Learning to Write Procedural Shaders

Ian-Max-Andolina · March 2, 2020, 12:19pm

In OpenGL, there is a system that allows for very fast drawing of 2D and 3D graphics, using a mini language that runs on the GPU called OpenGL Shading Language (GLSL). IN PTB, these are the Procedural stimuli, as seen in e.g. DriftDemo4.m or ProceduralGarboriumDemo.m.

There are many learning resources available, but IMO the best online tutorial about GLSL is the book of shaders:

It gives a thoughtful introduction to shaders, and includes a real-time real-time GLSL editor embedded in the web page to experiment with GLSL code:

It also includes a nice glossary of many GLSL functions that are very useful, e.g. smoothstep.

ShaderToy is another GLSL online editor that also allows sharing shader code; so I created an example which is the PTB procedural shader code used by DriftDemo4.m and converted to work in ShaderToy:

https://www.shadertoy.com/view/wlGXRV

You can change the various parameters and get a feel for how they affect the output immediately. What you are editing in ShaderToy is called a fragment shader. This is basically the equivalent of the BasicSineGratingShader.frag.txt file you will find in Psychtoolbox/PsychOpenGL/PsychGLSLShaders/.

So the order of code calls in PTB is:

DriftDemo4.m uses CreateProceduralSineGrating.m to create a procedural texture.
CreateProceduralSineGrating.m loads the GLSL code found in BasicSineGratingShader.vert.txt & BasicSineGratingShader.frag.txt.

If you make a shader in one of the online editors, you can transfer it back to PTB by getting the variables back into the correct places. Variables that may change on every frame should go into the auxParameters that get passed to Screen('DrawTexture'), and variables that don’t change too often can be specified in the CreateProceduralXXX.m setup file. EDIT: Mario reminded us the documentation for this is found here: http://psychtoolbox.org/docs/ProceduralShadingAPI

As another example, here is a red-green chromatic grating in shadertoy:

https://www.shadertoy.com/view/wtKSDw

And the equivalent PTB code:

github.com

iandol/opticka/blob/master/stimuli/CreateProceduralColorGrating.m

function [id, rect, shader] = CreateProceduralColorGrating(windowPtr, width, height, ...
	color1, color2, radius, normalise)
% [id, rect, shader] = CreateProceduralColorGrating(windowPtr, width, height [, color1=[1 0 0]]  [, color2=[0 1 0]] [, radius=0])
%
% A procedural color grating shader that can generate either sinusoidal or square gratings varying between two colors. Initial parameters are color1, color2 and radius. When drawing the shader using Screen('DrawTexture|s'), you can pass additional values:
% * baseColor is the base color from which color1 & color2 are mixed.
% * contrast is the mixing amount from baseColor to color1|2
% * sigma is a smoothing value, when sigma == -1 a sinusoidal grating is produced. when sigma >= 0 a square wave grating is produced using sigma value of smoothing at the edge. Smoothing for squarewave grating edges can reduce jumping artifacts when squarewave gratings are drifted. Smoothing uses GLSL smoothstep function (hermite interpolation).
% ====INPUT VALUES
% width, height = "virtual size" of the GLSL shader.
% color1 & color2 = two colors for the grating peaks to vary between. When running (see ColorGratingDemo), you can pass baseColor parameter, from which color1 and color2 will be modulated via the contrast parameter. When contrast == 0, then Color1 and color2 are the same as baseColor. As contrast increases each color is mixed with baseColor until at contrast == 1 the grating peaks are color1 and color2 exactly.Color mixing uses OpenGL's mix command. 
% radius = optional hard-edged circular mask sized in pixels
% normalise = do we use pow() to correct for a 2.2 gamma?
%
% ====RETURN VALUES
% id = texture pointer
% rect = default position rect
% shader = the GLSL shader, this is useful if you want to use glUniform commands to modify color 1, color2 or radius after texture creation.
%
% History:

This file has been truncated. show original

github.com

iandol/opticka/blob/master/stimuli/colorgrating.vert

/*
 * File: colorgrating.vert
 * Shader for drawing of color gratings.
 *
 * Copyright 2014, Ian Andolina <http://github.com/iandol>, licenced under the MIT Licence
 *
 */

/* Constants that we need 2*pi: */
const float     twopi = 6.2831853072;

/* Conversion factor from degrees to radians: */
const float     deg2rad = 3.141592654 / 180.0;

/* Attributes passed from Screen(): See the ProceduralShadingAPI.m file for infos: */
attribute vec4  modulateColor;
attribute vec4  auxParameters0;

/* Information passed to the fragment shader: Attributes and precalculated per patch constants: */
varying vec3    baseColor;

This file has been truncated. show original

github.com

iandol/opticka/blob/master/stimuli/colorgrating.frag

/*
 * File: colorgrating.frag
 * Shader for drawing of color gratings.
 *
 * Copyright 2014, Ian Andolina <http://github.com/iandol>, licenced under the MIT Licence
 *
 */

uniform vec2    center;
uniform vec4    color1;
uniform vec4    color2;
uniform float   radius;
uniform float   normalise;

varying vec3    baseColor;
varying float   alpha;
varying float   phase;
varying float   frequency;
varying float   sigma;
varying float   contrast;

This file has been truncated. show original

You can see how the variables are set up. In summary shaders are a fast and efficient way to draw stimuli, and although a bit daunting at first (lost outside the MATLAB IDE comfort zone), with these online real-time tools it makes learning how they work much easier.

bonus material: if you want to know how on earth occult tarot cards and GLSL GPU shaders are related, see https://patriciogonzalezvivo.github.io/PixelSpiritDeck/

mariokleiner · March 4, 2020, 6:15pm

Should also mention that there’s PTB documentation about how to communicate parameters between the shaders and PTB’s Screen(‘DrawTexture’,…) command:

help ProceduralShadingAPI, or
http://psychtoolbox.org/docs/ProceduralShadingAPI

Topic		Replies	Views
CreateProcedural* verbosity	4	315	August 20, 2017
GLSL dome shader	2	541	October 11, 2019
How to create bullseye stimuli in PTB? Programming Help	6	905	June 28, 2024
BlurredMipMap - but for Procedural textures? Programming Help experiment-design	9	282	November 5, 2023
PTB BETA UPDATED: Bugfixes and some improvements...	0	208	May 29, 2006

Learning to Write Procedural Shaders

Related topics