1. How to create shaders
2. How to build applications that use the shaders - API
1. How to create shaders
This is a very brief introduction to how the shaders in Shadertoy interface with the rendering platform of your choice (WebGL in the case of the web client, Opengl 2, Opengl 3 or Opengl 4 in case of the native app, OpenGL ES in case of the iOS version). The interface description contains what inputs and outputs are needed for the shaders to produce the images, the sound and the VR rendering.
Image shaders
Image shaders implement the mainImage() function in order to generate the procedural images by computing a color for each pixel. This function is expected to be called once per pixel, and it is responsability of the host application to provide the right inputs to it and get the output color from it and assign it to the screen pixel. The prototype is:
void mainImage( out vec4 fragColor, in vec2 fragCoord );
where fragCoord contains the pixel coordinates for which the shader needs to compute a color. The coordinates are in pixel units, ranging from 0.5 to resolution-0.5, over the rendering surface, where the resolution is passed to the shader through the iResolution uniform (see below).
The resulting color is gathered in fragColor as a four component vector, the last of which is ignored by the client. The result is gathered as an "out" variable in prevision of future addition of multiple render targets.
void mainImage( out vec4 fragColor, in vec2 fragCoord );
where fragCoord contains the pixel coordinates for which the shader needs to compute a color. The coordinates are in pixel units, ranging from 0.5 to resolution-0.5, over the rendering surface, where the resolution is passed to the shader through the iResolution uniform (see below).
The resulting color is gathered in fragColor as a four component vector, the last of which is ignored by the client. The result is gathered as an "out" variable in prevision of future addition of multiple render targets.
Sound shaders
Sound is generated by GLSL shaders through the mainSound() entrypoint, which has the following prototype:
vec2 mainSound( float time )
where the time variable contains the time, in seconds, of the sound sample for which the wave amplitude needs to be computed. This time will be sampled at a sample rate specified by the iSampleRate uniform, which typically will be 44100 or 48000 depending on the host application.
The desired wave amplitude is output as a pair of values, for stereo (left and right channel) sound, though the return value of the mainSound() function.
Shaders that implement the mainSound entrypoint will automatically be flagged as sound shaders and will be searchable though the filter system under the Sound Output qualifier.
vec2 mainSound( float time )
where the time variable contains the time, in seconds, of the sound sample for which the wave amplitude needs to be computed. This time will be sampled at a sample rate specified by the iSampleRate uniform, which typically will be 44100 or 48000 depending on the host application.
The desired wave amplitude is output as a pair of values, for stereo (left and right channel) sound, though the return value of the mainSound() function.
Shaders that implement the mainSound entrypoint will automatically be flagged as sound shaders and will be searchable though the filter system under the Sound Output qualifier.
VR shaders
Shadertoy shaders can create images for Virtual Reality (VR) mediums seamlessly. For that shaders must implement the mainVR() entry point, which is optional and has this prototype:
void mainVR( out vec4 fragColor, in vec2 fragCoord, in vec3 fragRayOri, in vec3 fragRayDir )
where fragCoord and fragColor work the same as in regular 2D image shaders: they contain the pixel coordinates in surface space and the output pixel color.
The variables fragRayOri and fragRayDir contain the ray origin and ray direction of the ray that goes through that pixel in the virtual world, given in tracker space. The shader is expected to transform these values into camera space if a moving camera is to be moved though the virtual world. The ray origin is given as variable and not uniform for VR systems where the camera is not modelled as a pinhole camera.
Shaders that implement the mainVR entrypoint will automatically be flagged as VR ready and will be searchable though the filter system under the VR qualifier.
void mainVR( out vec4 fragColor, in vec2 fragCoord, in vec3 fragRayOri, in vec3 fragRayDir )
where fragCoord and fragColor work the same as in regular 2D image shaders: they contain the pixel coordinates in surface space and the output pixel color.
The variables fragRayOri and fragRayDir contain the ray origin and ray direction of the ray that goes through that pixel in the virtual world, given in tracker space. The shader is expected to transform these values into camera space if a moving camera is to be moved though the virtual world. The ray origin is given as variable and not uniform for VR systems where the camera is not modelled as a pinhole camera.
Shaders that implement the mainVR entrypoint will automatically be flagged as VR ready and will be searchable though the filter system under the VR qualifier.
Input Uniforms
Shader can be fed with different types of per-frame static information by using the following uniform variables:
uniform vec3 iResolution;
uniform float iTime;
uniform float iTimeDelta;
uniform float iFrame;
uniform float iChannelTime[4];
uniform vec4 iMouse;
uniform vec4 iDate;
uniform float iSampleRate;
uniform vec3 iChannelResolution[4];
uniform samplerXX iChanneli;
uniform vec3 iResolution;
uniform float iTime;
uniform float iTimeDelta;
uniform float iFrame;
uniform float iChannelTime[4];
uniform vec4 iMouse;
uniform vec4 iDate;
uniform float iSampleRate;
uniform vec3 iChannelResolution[4];
uniform samplerXX iChanneli;
2. How to build applications that use the shaders
As of today, Shadertoy's API is open to all of you, let's get creative! Any developer can build apps (or webs) and access Shadertoys that have the right privacy settings ("Public + API").
Request Your Key
Sign In and come back to this page for instructions
What Can You Access?
After you request your API Key, you will be able to access your (and others') beloved Shadertoys from any website/app. This basically means that you can run queries on our database, and even download shaders to use them on your own software (check licenses).
If you can not see your shader listed in the API make sure the privacy of your shader is set to "Public + API", be aware that when you do that other users will be able to access/use your shaders.
If you can not see your shader listed in the API make sure the privacy of your shader is set to "Public + API", be aware that when you do that other users will be able to access/use your shaders.
Coding: Simple, Very Simple
All API calls require a key that you can request (check the first section of this page) for free and returns JSON files that you can easily read with your favorite parser.
Here are the basics of our API:
- Query shaders: as a developer you can pass any query to run on our database. This service will return an array of IDs.
https://www.shadertoy.com/api/v1/shaders/query/string?key=appkey
where string is your search string such as tags, usernames, words...
- Get a shader from a shader ID.
https://www.shadertoy.com/api/v1/shaders/shaderID?key=appkey
where shaderID is the same ID used in the Shadertoy URLs, and also the values returned by the "Query Shaders".
- Access the assets.
When you retrieve a shader you will see a key called "inputs", this can be a texture/video/keyboard/sound used by the shader. The JSON returned when accessing a shader will look like this:
[..]{"inputs":[{"id":17,"src":"/media/a/(hash.extension)","ctype":"texture","channel":0}[..]
To access this specific asset you can just cut and paste this path https://www.shadertoy.com/media/a/(hash.extension)
- Get all shaders.
https://www.shadertoy.com/api/v1/shaders?key=appkey
Advanced queries:
- Query shaders sorted by "name", "love", "popular", "newest", "hot" (by default, it uses "popular").
https://www.shadertoy.com/api/v1/shaders/query/string?sort=newest&key=appkey
- Query shaders with paging. Define a "from" and a "num" of shaders that you want (by default, there is no paging)
https://www.shadertoy.com/api/v1/shaders/query/string?from=5&num=25&key=appkey
- Query shaders with filters: "vr", "soundoutput", "soundinput", "webcam", "multipass", "musicstream" (by default, there is no filter)
https://www.shadertoy.com/api/v1/shaders/query/string?filter=vr&key=appkey
Source Code
Official Shadertoy App - Check our Github!
License
"Shadertoy.com API" is free and open. Shadertoy.com is not responsible for either the malfunctioning of the API or the malfunctioning of any of the shaders return by the API.
Since the API is part of Shadertoy.com, developers that use the API have to respect the terms of use. For example, developers must respect the specific licenses of each shader.
Any product (app, web...) that uses the "Shadertoy.com API", either free or commercial, must mention that uses "Shadertoy.com API".
Since the API is part of Shadertoy.com, developers that use the API have to respect the terms of use. For example, developers must respect the specific licenses of each shader.
Any product (app, web...) that uses the "Shadertoy.com API", either free or commercial, must mention that uses "Shadertoy.com API".