Shader Spec
Contents
Reference for writing effect shaders in Arshes. Shaders are written in Slang. The attributes and the resolution macros are defined in arshes.slang.
Entry Points
Fragment
Entry point. Receives UV (0.0-1.0) or custom VertexOutput, returns RGBA.
[shader("fragment")]
float4 fragmentMain(float2 uv : TEXCOORD) : SV_Target {
return float4(uv, 0.0, 1.0);
}Vertex (Optional)
Custom vertex shader with [primitive(type, count)]. Overrides default fullscreen quad.
struct VertexOutput {
float4 position : SV_Position;
float4 color : COLOR;
};
[primitive(4, 1000)]
[shader("vertex")]
VertexOutput vertexMain(uint vid : SV_VertexID, uint iid : SV_InstanceID) {
Particle p = particles[iid];
// vid: 0~3 (quad corners)
// iid: 0~999 (which particle)
}Compute (Optional)
Runs before fragment, in declaration order. Multiple compute shaders can be declared. Use [dispatch] and [numthreads] to set thread count. Sample textures with SampleLevel(samp, uv, 0). Sample() runs as level 0 on iOS, but on Android it requires the ComputeDerivativeGroupQuadsKHR capability, which most devices do not support.
uniform float microphone;
struct State {
float value;
};
[size(1)]
RWStructuredBuffer<State> state;
[dispatch(1, 1, 1)]
[numthreads(1, 1, 1)]
[shader("compute")]
void computeMain(uint3 id : SV_DispatchThreadID) {
state[0].value = lerp(state[0].value, microphone, 0.1);
}Built-in Uniforms
Values and textures provided by the engine. Declare them with the exact names below and they are bound automatically.
time
Elapsed time in seconds since the shader started. Resets on recompile.
uniform float time;deltaTime
Time in seconds since the last frame.
uniform float deltaTime;frame
Frame count since the shader started. Resets on recompile.
uniform int frame;resolution
Rendering resolution in pixels (width, height). RESOLUTION_X/Y macros are also available as int.
uniform float2 resolution;cameraTex
Camera RGB texture in linear color space (no color grading applied). The filter (color grading) and sRGB encoding are applied after your effect.
uniform Texture2D<float3> cameraTex;depthTex
Depth texture. Availability depends on the device. DEPTH_RESOLUTION_X / DEPTH_RESOLUTION_Y macros expose its dimensions as int.
uniform Texture2D<float> depthTex;backbuffer
Previous frame buffer.
uniform Texture2D<float4> backbuffer;blueNoiseTex
256x256 single-channel blue noise texture. Read exact texels with .Load(int3(px % 256, py % 256, 0)) to preserve the noise (no sampler filtering). Tileable across the 256x256 boundary.
uniform Texture2D<float> blueNoiseTex;sampler
Sampler state for texture sampling. Any name can be used.
uniform SamplerState sampler;microphone
Microphone input volume (RMS). Ranges from 0.0 to 1.0.
uniform float microphone;touch
Touch input. xy: position from (0,0) top-left to (1,1) bottom-right. z: 1.0 while touching, 0.0 when released. xy retains the last position, and is (-1,-1) before the first touch.
uniform float3 touch;cameraPosition
Camera world position. Declaring this uniform switches the camera to AR mode.
uniform float3 cameraPosition;invViewMatrix
Inverse view matrix of the camera. Declaring this uniform switches the camera to AR mode.
uniform float4x4 invViewMatrix;invProjectionMatrix
Inverse projection matrix of the camera. Declaring this uniform switches the camera to AR mode.
uniform float4x4 invProjectionMatrix;Read-Write Resources
Persistent resources you declare yourself (any name). Their contents survive across frames.
RWStructuredBuffer
Persistent read-write buffer. Supports custom structs. Use [size(N)] to set element count.
[size(4)]
RWStructuredBuffer<float4> state;RWTexture2D
Persistent read-write 2D texture. [size2d(w, h)] is required and sets the dimensions. If the name ends with "RW", a Texture2D declared with the same name minus "RW" refers to the same texture as read-only. Use it when you need a sampler. With a float element type, iOS stores 32-bit float and Android stores 16-bit float.
[size2d(RESOLUTION_X, RESOLUTION_Y)]
RWTexture2D<float4> canvasRW;
// read-only view of canvasRW
Texture2D<float4> canvas;Attributes
[range(min, max, default)]
Exposes a uniform float/int as a slider.
[range(0.0, 1.0, 0.5)]
uniform float brightness;[rgb(r, g, b)]
Exposes a uniform float3 as a color picker. Colors are authored in sRGB and automatically converted to linear before reaching your shader (your effect works in linear space), so the picked color appears as-is.
[rgb(1.0, 0.0, 0.0)]
uniform float3 tintColor;[rgba(r, g, b, a)]
Exposes a uniform float4 as a color picker with alpha. RGB is authored in sRGB and converted to linear automatically; alpha is passed through unchanged.
[rgba(1.0, 1.0, 1.0, 0.5)]
uniform float4 bgColor;[toggle(default)]
Exposes a uniform bool as a toggle.
[toggle(true)]
uniform bool useEffect;[size(N)]
Sets the element count for RWStructuredBuffer. Default: 1.
[size(64)]
RWStructuredBuffer<float4> particles;[size2d(w, h)]
Sets the texture dimensions for RWTexture2D. Use RESOLUTION_X/Y for screen-linked sizing, or DEPTH_RESOLUTION_X/Y for depth-linked sizing.
[size2d(RESOLUTION_X / 2, RESOLUTION_Y / 2)]
RWTexture2D<float4> canvas;[dispatch(x, y, z)]
Sets threadgroup count for a compute shader. Total threads = dispatch × numthreads.
[dispatch(RESOLUTION_X / 8, RESOLUTION_Y / 8, 1)]
[numthreads(8, 8, 1)]
[shader("compute")]
void computeMain(uint3 id : SV_DispatchThreadID) { }[primitive(type, count)]
Defines geometry for a custom vertex shader. type: verts per primitive (1=point, 3=tri, 4=quad). count: instances.
[primitive(4, 1000)]
[shader("vertex")]
VertexOutput vertexMain(uint vid : SV_VertexID, uint iid : SV_InstanceID) {
// vid: 0~3 (quad corners), iid: 0~999 (particle index)
}[pass(index)]
Defines multi-pass rendering. Passes render sequentially (pass 0 clears, 1+ preserves). Max 8.
[pass(0)]
[shader("fragment")]
float4 background(float2 uv : TEXCOORD) : SV_Target {
return float4(uv, 0.5, 1.0);
}
[pass(1)]
[primitive(3, 1)]
[shader("vertex")]
VertexOutput triVert(uint vid : SV_VertexID, uint iid : SV_InstanceID) { ... }
[pass(1)]
[shader("fragment")]
float4 triangle(VertexOutput input) : SV_Target {
return input.color;
}[blend(blendMode)]
Sets blend mode: BlendMode.None (overwrite), BlendMode.Additive (src+dst), BlendMode.Alpha (standard alpha blend).
[blend(BlendMode.Alpha)]
[shader("fragment")]
float4 overlay(float2 uv : TEXCOORD) : SV_Target {
float d = length(uv - 0.5);
float alpha = smoothstep(0.3, 0.2, d);
return float4(1.0, 0.5, 0.0, alpha);
}