Shaderplayer

An execution environment for GPU fragment shaders



Download




Screenshots






Desktop embedding


MS Windows



XWindows (X11)



This website does NOT use HTML <FRAME>s.

Documentation

Shaderplayer v3.0.2 Copyright 2020 Theron Tarigo This alpha-quality software release may be used freely, however it may not be copied. Additional copies may be obtained by request from the author.
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
_______________________________________________________________________________ === Introduction ==============================================================
Shaderplayer is an execution environment for GPU fragment shaders written in the OpenGL GLSL ES 3.0 shading language. Each shader is drawn to a rectangular canvas which may be either displayed in a desktop window, used as a texture for other shaders and subsequent frames, or read as a sound signal and played through system sound output.
Shaderplayer is inspired by the website Shadertoy.com, and many shader programs are compatible with both environments.
A collection of cooperating shader programs consists of a directory (the "Source Directory") containing source files with .glsl file extension and optionally a texture input specification and image source files. The Source Directory is determined as the current working directory (which may be the directory the Shaderplayer executable is launched from) or as specified by command-line argument.
The name of each source file specifies its output: image.glsl - displayed on screen Buf*.glsl - rendered to a texture - * is A, B, C, or D sound.glsl - outputted to audio device SndBufA.glsl - rendered to a texture (sound output clock domain) common.glsl - source is prepended to all other sources when compiling WindowIcon.glsl - rendered once and used as the image output window icon On startup, Shaderplayer will compile all recognized GLSL files in the Source Directory. Any warnings or errors will be printed to standard error (or displayed in the console). The presence of errors will result in Shaderplayer exiting immediately.
_______________________________________________________________________________ === Image Display =============================================================
The minimum requirement to run Shaderplayer is the image.glsl file, which must provide a valid GLSL implementation of the entrypoint void mainImage( out vec4 fragColor, in vec2 fragCoord ); where - fragCoord is the fragment position given by gl_FragCoord.xy, ranging from (vec2(.5)) to (iResolution.xy-.5). - fragColor is the RGBA value used as output.
If image.glsl does not exist, a simple demonstration will be created.
Most displays interpret RGB values as outputted from image.glsl in the sRGB colorspace, which approximately uses a gamma of 2.2. Therefore, to achieve linear luminance output, the final step of mainImage should be a conversion such as fragColor.rgb = pow( fragColor.rgb, vec3( 1./2.2 ) ); Most shaders on Shadertoy.com using linear luminance values for rendering use an equivalent conversion. Therefore, the above should always be used, rather than a "True sRGB" conversion, as Shaderplayer may apply additional corrections to convert from Gamma=2.2 to True sRGB. Failure to convert from sRGB to the colorspace of a connected display which does not use sRGB is a BUG in Shaderplayer.
The alpha (.a) output component is unused.
_______________________________________________________________________________ === Sound Output ==============================================================
Sound output may be generated by providing the sound.glsl file, which must provide a valid GLSL implementation of one of the following entrypoints, with the associated #define somewhere in the file.
#define MAINSOUND_INTEGER_PARTIAL vec2 mainSound( int sampleNumber, int partialNumber ); #define MAINSOUND_INTEGER vec2 mainSound( int sampleNumber ); // define nothing (compatible with Shadertoy.com) vec2 mainSound( float sampleTime ); where - sampleNumber is the index of the sample of audio output being generated. - partialNumber is an index in the range (0) to (iSoundPartials-1); Work is divided between these partials and results are summed. - sampleTime is playback time corresponding to the sample of audio output being generated. - The return value is a stereo sample value, with x,y as left,right channels Using floating-point sampleTime will lead to errors due to imprecise phase calculation, and usually causes audible aliasing after the first few seconds of sound synthesis.
Using integer sample number may also lead to such errors if not handled with great care.
_______________________________________________________________________________ === Image Buffer ==============================================================
An image (or control data) may be drawn to a texture by implementing mainImage inside a Buf*.glsl file, where * is A, B, C, or D, up to four such Image Buffer shaders. All output values (.rgba) are captured in the texture buffer and no conversions are performed.
As with the Image Shader, fragCoord is the fragment position given by gl_FragCoord.xy, ranging from (vec2(.5)) to (iResolution.xy-.5).
Image Buffers are updated in A,B,C,D order once for every frame of the Image output.
_______________________________________________________________________________ === Sound-Synchronous Buffer ==================================================
Control data (or an image) may be drawn to a texture by implementing mainImage in the SndBufA.glsl file. All output values (.rgba) are captured in the texture buffer and no conversions are performed.
Unlike the image buffers and output, this buffer has a fixed size of 512x512, with fragCoord ranging accordingly.
This buffer is updated once for every segment of sound output generated, and may be updated multiple times during the rendering of any of the image shaders. As a result, accessing this buffer's texture from an image shader is atomic but incoherent; accessed values may be inconsistent across an image buffer.
_______________________________________________________________________________ === Common Source =============================================================
The contents of common.glsl are included before the contents of each other source file when compiling the associated shader. As a result, declarations and definitions from this file are made avaiable to the other shaders.
This source needn't define any particular function, but may also define entrypoints such as mainSound or mainImage. The primary source file for the shader which makes use of this must still exist, as long as it does not contain a conflicting implementation of the entrypoint, and may be an empty file.
_______________________________________________________________________________ === Window Icon ===============================================================
The desktop window icon of the image display window may be drawn by implementing mainImage in the WindowIcon.glsl file.
The buffer will be square and have a relatively small number of pixels in width and height, with iResolution.xy set accordingly.
The alpha (.a) output component is used for opacity.
_______________________________________________________________________________ === Uniforms ==================================================================
The following uniform parameters are available in each shader: uniform vec3 iResolution; // Buffer or output size in pixels uniform float iTime; // Run time in seconds uniform float iTimeDelta; // Change in iTime since last frame uniform int iFrame; // Index of frame since start uniform float iChannelTime[4]; // Playback time of a source uniform vec3 iChannelResolution[4]; // Image size of a source uniform vec4 iMouse; /* Mouse click/drag position: xy: most recent position (updated only when left button is down) abs(zw): position before start of drag sign(z): positive if left button is down */ uniform vec4 iDate; /* Local clock time: xyzw: year, month, day (indexed from 1), time (seconds since midnight) */ uniform float iSampleRate; // Sound output samples per second The following texture sampler handles are available: uniform sampler2D iChannel0; // Input slot 0 uniform sampler2D iChannel1; // Input slot 1 uniform sampler2D iChannel2; // Input slot 2 uniform sampler2D iChannel3; // Input slot 3
_______________________________________________________________________________ === Texture source specification ==============================================
Texture sources must be specified in the layout file. The file is a list of words of the form "shader:" or "slot=source" separated by whitespace.
"shader:" sets to which shader the following source specifications apply, where "shader" is Image, Sound, BufA/B/C/D, SndBufA, or WindowIcon.
"slot=source" assigns a source to an input slot, where "slot" is 0, 1, 2, or 3, and "source" is one of the following: img:filename where "filename" is an image file supported by STB lib [1]. buf:* where * is A, B, C, D, or SndA - the corresponding buffer: A,B,C,D: An Image Buffer. SndA: SndBufA. keyboard - Current keyboard state. Rows 0,1,2: down, press, toggle. sound - Generated sound output [1] https://github.com/nothings/stb/blob/0224a44a10564a214595797b4c88323f79a5f934/stb_image.h
_______________________________________________________________________________ === Key bindings ==============================================================
These keybindings are hardcoded in Shaderplayer v3.0.x. Other keys are available to the shaders in the "keyboard" texture input.
R - Reload shader sources from disk and recompile. Left - Decrement iTime 1 second. Right - Increment iTime 1 second. Down - Decrement iTime 10 seconds. Up - Increment iTime 10 seconds. PgDn - Decrement iTime 1 minute. PgUp - Increment iTime 1 minute. Home - Decrement iTime 1 hour. End - Increment iTime 1 hour. Space - Pause shader execution. Mouse and keyboard interaction will continue to trigger new frames. Useful for saving power or tweaking an iTime-dependent shader at specific time.
A future release of Shaderplayer will remove these default bindings and provide an alternative for accessing these functionalities.
_______________________________________________________________________________ === Command-line options ======================================================
Various Shaderplayer defaults may be overridden using command-line flags when starting Shaderplayer: -s WxH - Set the initial window size in pixels. -m X,Y - Set the initial iMouse.xy value. -d - Embed Shaderplayer into the desktop background. -r rate - Set the audio output sample rate in Hz. -b samples - Set audio output buffer latency target length in samples. -g - Enable interleaving audio frame rendering with image rendering. Allows higher sound generation performance at lower latencies. -o - Save all sound output to a file. The format is raw stereo Float32LE pcm.
_______________________________________________________________________________ === Bugs, Unimplemented Shadertoy.com features, and compatibility notes ======= To be written.
_______________________________________________________________________________ === Contributors ==============================================================
Many thanks to the following people for helping to test and having patience with tedious debug builds: Cole Yarbrough Alexander Mai Finley Hebert-Perkins