GPU shader toolkit

Expert GPU shader development toolkit covering HLSL, GLSL, MSL, WGSL, ReShade FX, Unity ShaderLab, and WebGL. Features cross-language conversion, GPU performance optimization, noise/lighting functions, platform gotchas, debugging, production-ready templates, NVIDIA shader cache analysis with nvcachetools/nvdisasm/envytools for compiled shader reverse engineering, DirectX shader decompilation, game shader PAK file reverse engineering and DXBC disassembly for extracting compiled shaders from game archives (Warframe/EvoEngine-style), PSP/PPSSPP GE dump (.ppdmp) analysis for extracting generated shaders from PSP games, and advanced performance optimization based on compiled shader analysis.

Expert-level GPU shader development, optimization, reverse engineering, and conversion across all major shader languages and platforms.

---

Quick Reference

Language Detection (One Glance)

Pattern	Language
SV_Position, cbuffer, register(b0)	HLSL
gl_Position, uniform, layout(binding=)	GLSL
[[position]], [[buffer(0)]], metal_stdlib	MSL
@vertex, @fragment, @binding(0)	WGSL
technique, pass, tex2D(, ui_type=	ReShade FX
Shader "...", Properties, SubShader	Unity ShaderLab
attribute, varying, precision mediump	GLSL ES 1.00 (WebGL 1)
in, out, layout(location=), #version 300	GLSL ES 3.00 (WebGL 2)

Type Quick Reference

HLSL	GLSL	MSL	WGSL
float2	vec2	float2	vec2<f32>
float3	vec3	float3	vec3<f32>
float4	vec4	float4	vec4<f32>
float3x3	mat3	float3x3	mat3x3<f32>
float4x4	mat4	float4x4	mat4x4<f32>

Function Quick Reference

Operation	HLSL	GLSL
Fractional	frac(x)	fract(x)
Lerp	lerp(a,b,t)	mix(a,b,t)
Saturate	saturate(x)	clamp(x,0,1)
Mod	fmod(a,b)	mod(a,b)
Texture	tex.Sample(s,uv)	texture(tex,uv)
DDX	ddx(x)	dFdx(x)

Performance Critical Patterns

hlsl

// ALWAYS use sincos instead of separate sin/cos
float s, c; sincos(angle, s, c);  // NOT: s=sin(a); c=cos(a);

// ALWAYS use multiply instead of pow for integers
float x2 = x * x;    // NOT: pow(x, 2.0)
float x3 = x * x * x; // NOT: pow(x, 3.0)

// ALWAYS use saturate instead of clamp to 0-1
float x = saturate(x);  // NOT: clamp(x, 0.0, 1.0)

// ALWAYS use dot for squared length
float lenSq = dot(v, v);  // NOT: length(v) * length(v)

---

Supported Languages

Language	Platform	Extensions
HLSL	DirectX, Unity, Unreal	.hlsl, .fx, .hlsli
GLSL	OpenGL, Vulkan, WebGL	.glsl, .vert, .frag, .comp, .geom
MSL	Metal (Apple/iOS/macOS)	.metal
WGSL	WebGPU	.wgsl
ReShade FX	ReShade Post-Processing	.fx
ShaderLab	Unity Shaders	.shader
GLSL ES	WebGL 1.0/2.0	.glsl, embedded

---

Shader Cache Reverse Engineering (NVIDIA)

Overview

This section covers extracting and analyzing compiled NVIDIA GPU shaders from the driver's shader cache. This enables performance optimization, debugging, and understanding how your GLSL/HLSL code compiles to GPU assembly.

Tools Required

Tool	Purpose	Source
nvcachetools	Extract compiled shaders from NVIDIA cache	github.com/therontarigo/nvcachetools
nvdisasm	NVIDIA proprietary disassembler	CUDA Toolkit or standalone
envytools	Open-source NVIDIA disassembler	github.com/envytools/envytools
dx-shader-decompiler	DirectX 9 shader decompiler	github.com/aizvorski/dx-shader-decompiler

---

NVIDIA Shader Cache Workflow

Step 1: Enable and Locate Shader Cache

bash

# Default cache locations
# Linux:   ~/.nv/GLCache/
# Windows: %LOCALAPPDATA%\NVIDIA\GLCache\

# Ensure cache directory exists
mkdir -p ~/.nv/GLCache

# Or set custom cache path
export __GL_SHADER_DISK_CACHE_PATH=/path/to/cache

Important: The cache directory may not exist by default. Create it manually or the driver won't save shader caches.

Step 2: Build nvcachetools

bash

git clone https://github.com/therontarigo/nvcachetools.git
cd nvcachetools

# Build nvcachedec (extracts .toc/.bin to .nvuc files)
gcc -o nvcachedec nvcachedec.c

# Build nvucdump (extracts sections from .nvuc files)
gcc -o nvucdump nvucdump.c

Step 3: Extract Compiled Shaders

bash

# Extract shaders from cache TOC file
# Creates object00000.nvuc, object00001.nvuc, etc.
./nvcachedec path/to/cache/*.toc output_objs/

# Extract sections from NVUC files
# Creates section4_0001.bin, etc.
./nvucdump output_objs/object00000.nvuc sections/

Step 4: Disassemble with nvdisasm

bash

# Using NVIDIA's proprietary disassembler
# SM architecture codes:
# SM50 - Maxwell (GTX 750, 900 series)
# SM60 - Pascal (GTX 1000 series)
# SM70 - Volta
# SM75 - Turing (GTX 1600, RTX 2000 series)
# SM80 - Ampere (RTX 3000 series)
# SM89 - Ada Lovelace (RTX 4000 series)

nvdisasm --binary SM89 output_objs/object00000.nvuc
nvdisasm --binary SM75 output_objs/object00000.nvuc

Step 5: Disassemble with envytools (Open Source)

bash

# Using open-source envydis
# -i: interactive mode
# -mgm107: Maxwell GM107 architecture
./envydis -i -mgm107 sections/section4_0001.bin

---

Analyzing Compiled Shader Output

Instruction Count Statistics

bash

# Count instruction frequency in compiled shader
nvdisasm --print-code --binary SM87 object.nvuc | \
  sed '1d' | \
  sed -e 's/@[!|A-Za-z0-9]* / /g' | \
  perl -p0 -e 's#/\*.*?\*/##sg' | \
  sed "s/^[{|}| \t]*//" | \
  sed 's/\s.*$//' | \
  sort | uniq -c

Key Performance Instructions

Instruction	Meaning	Performance Impact
STL	Store to Local Memory	HIGH - Often indicates array usage slowdown
LDL	Load from Local Memory	HIGH - Paired with STL, memory access
FFMA_FP32	Fused Multiply-Add	Medium - Basic math operation
FMUL/FADD	Multiply/Add	Low - Simple ALU operations
MUFU.SIN/COS	Transcendental sin/cos	High - Expensive operations
TEX	Texture sampling	Variable - Depends on cache hits

---

NVIDIA-Specific Optimization Insights

STL (Store to Local Memory) Optimization

Problem: NVIDIA OpenGL compiler can generate excessive STL instructions when using arrays, causing major slowdowns.

Symptoms:

• Shader runs slowly in OpenGL but fast in Vulkan
• Large arrays (especially int[200+]) trigger STL explosions
• Array copies as function arguments cause STL chains

Solutions:

glsl

// BEFORE: Large int array - causes STL explosion
int map[220];  // Each element stored to local memory
for(int i=0; i<220; i++) map[i] = 0;

// AFTER: Packed into uint array - much smaller
uint map[7];   // 7 * 32 = 224 bits, enough for 220 flags
for(int i=0; i<7; i++) map[i] = 0u;

// Bit access functions
bool getBit(uint map[7], int index) {
    return (map[index/32] & (1u << (index%32))) != 0u;
}
void setBit(inout uint map[7], int index) {
    map[index/32] |= (1u << (index%32));
}

CONST (Constants) Memory Optimization

Problem: Too many unique float constants can degrade performance significantly.

Guideline: Keep constant data under 1-2 KB for optimal performance on most NVIDIA GPUs.

glsl

// BEFORE: Many unique floats (slow)
const mat4 weights[64] = mat4[64](
    mat4(0.01234, 0.05678, 0.09123, ...),
    mat4(0.03456, 0.07890, 0.01234, ...),
    // ... many unique values
);

// AFTER: Quantized floats (faster, minor quality loss)
// Round floats to fewer unique values
const mat4 weights[64] = mat4[64](
    mat4(0.012, 0.057, 0.091, ...),  // Rounded to ~1/100 precision
    mat4(0.035, 0.079, 0.012, ...),
    // ... fewer unique values = less CONST memory
);

Quantization Script (Python):

python

# cfloats.py - Quantize float constants
def quantize_floats(floats, scale=132.0):
    """Reduce unique floats by quantizing to scale bins"""
    return [round(f * scale) / scale for f in floats]

# Example: 0.011, 0.012, 0.0115 -> all become 0.011 with scale=132

---

OpenGL vs Vulkan Compiler Differences

NVIDIA's OpenGL and Vulkan shaders can compile differently:

bash

# Compare same shader compiled in OpenGL vs Vulkan
# OpenGL cache location
~/.nv/GLCache/<hash>/nvcache.toc

# Run application with OpenGL, extract
nvcachedec opengl_cache/*.toc ogl_objs/

# Run same application with Vulkan, extract  
nvcachedec vulkan_cache/*.toc vk_objs/

# Compare instruction counts
nvdisasm --print-code --binary SM87 ogl_objs/object00000.nvuc | wc -l
nvdisasm --print-code --binary SM87 vk_objs/object00000.nvuc | wc -l

Common Findings:

• Vulkan compiler (via glslangValidator) often optimizes better
• OpenGL-only STL slowdowns may not appear in Vulkan
• Same GLSL can produce very different assembly

---

Shader Architecture Reference (SM Codes)

Architecture	SM Code	GPUs	Year
Maxwell	SM50/SM52	GTX 750, 900 series	2014
Pascal	SM60/SM61	GTX 1000 series	2016
Volta	SM70	Titan V, V100	2017
Turing	SM75	RTX 2000, GTX 1600	2018
Ampere	SM80/SM86	RTX 3000, A100	2020
Ada Lovelace	SM89	RTX 4000 series	2022

---

Troubleshooting NVIDIA Shader Cache

Driver Version Changes (550+)

bash

# Nvidia 550+ drivers changed binary format for Vulkan shaders
# Check if extraction fails
nvcachedec cache/*.toc output/
# If OpenGL shaders work but Vulkan don't, check:
# https://github.com/therontarigo/nvcachetools/issues/1

Cache Not Being Created

bash

# Ensure cache directory exists
mkdir -p ~/.nv/GLCache

# Enable shader cache in NVIDIA settings
nvidia-settings -a ShaderCacheSize=10

# Or via environment
export __GL_SHADER_DISK_CACHE=1
export __GL_SHADER_DISK_CACHE_PATH=~/.nv/GLCache

Browser Cache (Encrypted)

Chrome and other browsers encrypt their shader caches, making them unusable with nvcachetools. Use minimal launchers instead:

• Vulkan: vulkan-shadertoy-launcher
• OpenGL: Custom minimal OpenGL context

---

DirectX Shader Decompilation

DX9 Shader Decompilation

For DirectX 9 pixel/vertex shaders (SM 3.0):

bash

# Get the tool
git clone https://github.com/aizvorski/dx-shader-decompiler.git
cd dx-shader-decompiler

# Decompile DX9 shader binary
python dx-shader-decompiler.py shader.bin

# Output: HLSL-like decompiled code

Supported Formats:

• Pixel Shader 3.0 (ps_3_0)
• Vertex Shader 3.0 (vs_3_0)

DX10/11/12 Shader Analysis

For modern DirectX shaders (SM 4.0+):

bash

# Use Microsoft's DirectX Shader Compiler (DXC) disassembler
dxc -dumpbin shader.dxil -Fc output.txt

# Or use AMD's RDNA shader analyzer
# Or use RenderDoc for runtime capture

---

PSP/PPSSPP Shader Analysis

Important: PSP Games Don't Have Traditional Shaders

Critical Understanding: PSP games use a fixed-function graphics pipeline with a programmable GPU called the "Graphics Engine" (GE). They do NOT contain shader code. Instead, PSP games use:

• GE command lists (display lists)
• Fixed-function rendering states (lighting, texturing, blending)
• Transform matrices and vertex processing

PPSSPP generates shaders at runtime by translating PSP GE commands into modern GLSL/HLSL/SPIR-V based on the current rendering state.

---

PPSSPP Dump Files

File Type	Location	Contents	Use Case
.ppdmp	SYSTEM/DUMP/	GE frame dump (raw GE commands)	Primary analysis target
.glshadercache	SYSTEM/CACHE/	Compiled OpenGL shaders	Not useful - compiled
.vkshadercache	SYSTEM/CACHE/	Compiled Vulkan shaders	Not useful - compiled

Note: Use .ppdmp files for shader analysis, NOT the compiled shader caches.

---

Creating .ppdmp Frame Dumps

1. Open PPSSPP and load your game
2. Go to Debug → GE debugger... (Desktop versions only)
3. When the scene you want to capture is visible, click "Record" in the top right
4. After ~1 second, click "Stop"
5. Save the .ppdmp file to SYSTEM/DUMP/

Wiki Reference: https://github.com/hrydgard/ppsspp/wiki/How-to-create-a-frame-dump

---

.ppdmp File Format Structure

Header (24 bytes)

cpp

struct Header {
    char magic[8];        // "PPSSPPGE"
    uint32_t version;     // Current version: 6
    char gameID[9];       // Game disc ID (e.g., "ULUS12345")
    uint8_t pad[3];       // Padding
};

Version History

Version	Features
1	Uncompressed (deprecated)
2	Snappy compression (minimum supported)
3	Adds FRAMEBUF0-FRAMEBUF9
4	Expanded header with game ID
5	zstd compression (current)
6	Corrects dirty VRAM flag

Command Types

cpp

enum class CommandType : u8 {
    INIT = 0,           // Initial GPU state (512 * 4 bytes)
    REGISTERS = 1,      // GE register commands
    VERTICES = 2,       // Vertex data
    INDICES = 3,        // Index data
    CLUT = 4,           // Color Lookup Table data
    TRANSFERSRC = 5,    // Transfer source data
    TEXTURE0 = 0x10,    // Texture level 0-7 data
    FRAMEBUF0 = 0x18,   // Framebuffer data
    // ... etc
};

File Layout

text

[Header: 24 bytes]
[Command Count: 4 bytes]
[Push Buffer Size: 4 bytes]
[Compressed Commands Array: zstd]
[Compressed Push Buffer: zstd]

---

Extracting Shader Information from .ppdmp

Key Insight: Shaders are NOT stored in .ppdmp files. They are regenerated from GE state during playback.

Workflow to Extract Generated Shaders

1. Parse .ppdmp file:

   • Validate magic = "PPSSPPGE"
   • Decompress commands and push buffer using zstd
   • Process INIT command for initial GPU state

2. Reconstruct GPU State:

   • INIT command contains 512 bytes of GE register state
   • REGISTERS commands update state during playback

3. Compute Shader IDs:

   • ComputeVertexShaderID() creates 64-bit ID from GE state
   • ComputeFragmentShaderID() creates fragment shader ID

4. Generate Shader Code:

   • GenerateVertexShader() produces GLSL/HLSL
   • GenerateFragmentShader() produces fragment shader

Key Shader ID Bits

Vertex Shader Bits:

Bit	Meaning
VS_BIT_IS_THROUGH	Through mode (no transform)
VS_BIT_USE_HW_TRANSFORM	Hardware transform
VS_BIT_LIGHTING_ENABLE	Lighting enabled
VS_BIT_HAS_NORMAL	Has normal vectors
VS_BIT_UVGEN_MODE	UV generation mode
Bone/skinning weights	Up to 8 bones

Fragment Shader Bits:

Bit	Meaning
FS_BIT_CLEARMODE	Clear mode
FS_BIT_DO_TEXTURE	Texturing enabled
FS_BIT_ALPHA_TEST	Alpha test
FS_BIT_COLOR_TEST	Color test
Blend modes	Various blend functions

---

PPSSPP Source Code Reference

File	Purpose
GPU/Debugger/RecordFormat.h	File format structures
GPU/Debugger/Record.cpp	Recording implementation
GPU/Debugger/Playback.cpp	Playback/replay
GPU/Common/ShaderId.cpp	Shader ID computation
GPU/Common/VertexShaderGenerator.cpp	Vertex shader generation
GPU/Common/FragmentShaderGenerator.cpp	Fragment shader generation
GPU/GPUState.h	GE state structures
GPU/ge_constants.h	GE command constants

---

Parsing .ppdmp Example (C++)

cpp

#include <zstd.h>
#include "GPU/Debugger/RecordFormat.h"

bool ParsePPDMP(const char* filename) {
    FILE* fp = fopen(filename, "rb");

    // Read header
    GPURecord::Header header;
    fread(&header, sizeof(header), 1, fp);

    if (memcmp(header.magic, "PPSSPPGE", 8) != 0) return false;
    if (header.version < 2 || header.version > 6) return false;

    // Read sizes
    uint32_t cmdCount, bufSize;
    fread(&cmdCount, sizeof(cmdCount), 1, fp);
    fread(&bufSize, sizeof(bufSize), 1, fp);

    // Read and decompress commands
    uint32_t compressedSize;
    fread(&compressedSize, sizeof(compressedSize), 1, fp);
    uint8_t* compressed = new uint8_t[compressedSize];
    fread(compressed, compressedSize, 1, fp);

    std::vector<GPURecord::Command> commands(cmdCount);
    ZSTD_decompress(commands.data(), cmdCount * sizeof(GPURecord::Command),
                    compressed, compressedSize);

    // Process commands
    for (const auto& cmd : commands) {
        switch (cmd.type) {
            case GPURecord::CommandType::INIT:
                // Initial GE state - 512 * 4 bytes of registers
                break;
            case GPURecord::CommandType::REGISTERS:
                // GE command list
                break;
            // ... handle other types
        }
    }
    return true;
}

---

Tools for PSP Shader Analysis

Tool	Purpose
PPSSPP GE Debugger	Built-in frame analysis (Debug menu)
PPSSPP Shader Viewer	View generated shaders in developer tools
RenderDoc	Capture PPSSPP's Vulkan/D3D output
Custom Parser	Parse .ppdmp for batch analysis

Summary: PSP Shader Extraction

What You Want	How To Get It
Game's rendering commands	GE Frame Dump (.ppdmp file)
PPSSPP's generated shaders	Use GE Debugger or parse dump
Understand shader generation	Read ShaderGenerator.cpp files
Debug graphics issues	GE Debugger (Debug menu)

---

Game Shader PAK File Extraction

Overview

Many games ship compiled shaders in proprietary .pak archive files. This section covers reverse-engineering the PAK file format, extracting embedded shader binaries, and disassembling the contained DXBC (DirectX Bytecode) back into readable assembly. The methodology below was developed through actual extraction of 678 DX11 shaders from a Warframe _wfshadersdx11.pak file and is applicable to any game using similar archive patterns.

When to Use This

• You have a .pak, .package, .bundle, or similar game archive containing compiled shaders
• You want to understand a game's rendering techniques by examining its shaders
• You need to extract shader bytecode for further analysis with external tools (DXC, RenderDoc)
• You're doing modding work and need to understand shader resource bindings

General Approach: Format Reverse Engineering

Step 1: File Identification

Before writing any code, examine the file with hex tools to understand its structure:

bash

# Quick hex survey of the first 256 bytes
xxd -l 256 shader.pak | head -16

# Check file size
cstat --printf='%s' shader.pak | numfmt --to=iec

# Search for known magic bytes (DXBC, RDEF, ISGN, SHEX, etc.)
rg -c 'DXBC|SHEX|SHDR|RDEF|ISGN|OSGN|STAT' shader.pak

Step 2: Find the Table of Contents (TOC)

Look for repeating patterns that indicate file entries. Common TOC markers:

Pattern	Engine/Game	Example
FILELINK_____END	Warframe/EvoEngine	_wfshadersdx11.pak
PK_ (zip-like)	Various	Standard ZIP archives
FSB5	FMOD	Audio banks
RIFF/WAVE	Generic	RIFF containers
Repeating 4-byte offsets	Unreal	.pak files

bash

# Count occurrences of potential TOC markers
rg -c 'FILELINK' shader.pak

# Look for null-delimited string tables near file start
strings -t x shader.pak | head -50

Step 3: Map the Header

Most PAK files have a small fixed-size header at offset 0:

python

import struct

# Read potential header fields
data = open('shader.pak', 'rb').read()

# Try interpreting first 8 bytes as two uint32s
offset_field = struct.unpack_from('<I', data, 0)[0]
count_field = struct.unpack_from('<I', data, 4)[0]

print(f"First u32: 0x{offset_field:08x} ({offset_field})")
print(f"Second u32: {count_field}")

# Validate: does offset_field point to a data region?
# Does count_field match the number of TOC entries?

Warframe/EvoEngine PAK Format (Verified)

This format was fully reverse-engineered from _wfshadersdx11.pak:

PAK Header (8 bytes)

text

Offset  Size  Field
0x00    4     data_section_offset  (e.g., 0x0000CF70)
0x04    4     entry_count         (e.g., 713)

TOC Format (entries between header and data section)

Each TOC entry is delimited by the 16-byte marker FILELINK_____END:

text

[FILELINK_____END] [padding: NUL bytes]
[4 bytes: file_offset_within_data_section]
[4 bytes: file_size]
[NUL-terminated string: filename] (e.g., "envmesh:terrain_vsh_5.sdrb")

Per-File Format (SDRB wrapper)

Each .sdrb file inside the PAK has a two-layer header before the actual DXBC:

text

[16 bytes: "MANAGEDFILE_DATA"]       <- EvoEngine resource marker
[48 bytes: "BLOCK_USED_IN_ENGINE____________END"]  <- Engine metadata block
[DXBC shader bytecode]               <- Standard Microsoft DirectX bytecode

Key insight: The DXBC starts at variable offset within each SDRB file. Use find(b'DXBC') rather than a fixed offset.

DXBC Format (Standard Microsoft)

text

Offset  Size  Field
0x00    4     "DXBC" magic
0x04    16    Content hash (SHA-1 like)
0x14    4     Version (e.g., 0x00050000 for SM5.0)
0x18    4     Total DXBC size in bytes
0x1C    4     Chunk count
0x20    N*4   Chunk offset table (N = chunk count)
[chunk data...]

DXBC Chunk Types

Chunk	Description	What It Contains
RDEF	Resource Definitions	Constant buffer layouts, texture bindings, sampler bindings, variable names
ISGN	Input Signature	Vertex inputs (position, normal, UV) or pixel shader inputs from interpolators
OSGN	Output Signature	Vertex outputs (SV_Position, texcoords) or pixel shader color outputs (SV_TARGET)
SHEX	Shader Executable	The actual compiled bytecode (DXBC assembly) - SM4/SM5 instructions
SHDR	Shader Executable (legacy)	Same as SHEX but for older SM2/SM3 shaders
STAT	Statistics	Instruction count, temp register count, texture load count

Extraction Script (Python)

A complete, tested extraction script for this PAK format:

python

#!/usr/bin/env python3
"""
Generic game shader PAK extractor - Warframe/EvoEngine format.
Usage: python extract_shaders.py <input.pak> <output_dir>
"""
import struct, os, sys
from collections import defaultdict

def read_u32(data, offset):
    return struct.unpack_from('<I', data, offset)[0]

def read_str(data, offset):
    end = offset
    while end < len(data) and data[end] != 0:
        end += 1
    return data[offset:end].decode('ascii', errors='replace')

def parse_pak_toc(pak_data):
    """Parse PAK TOC: header + FILELINK-delimited entries."""
    data_start = read_u32(pak_data, 0)
    entry_count = read_u32(pak_data, 4)
    marker = b'FILELINK_____END'

    # Find all marker positions in TOC region
    positions = []
    pos = 8
    while pos < data_start:
        idx = pak_data.find(marker, pos, data_start)
        if idx == -1:
            break
        positions.append(idx)
        pos = idx + len(marker)

    entries = []
    for i in range(len(positions)):
        entry_start = positions[i] + len(marker)
        entry_end = positions[i + 1] if i + 1 < len(positions) else data_start
        entry_data = pak_data[entry_start:entry_end]

        # Skip leading NULs
        j = 0
        while j < len(entry_data) and entry_data[j] == 0:
            j += 1
        remaining = entry_data[j:]

        if len(remaining) < 8:
            continue

        file_offset = read_u32(remaining, 0)
        file_size = read_u32(remaining, 4)
        nul = remaining.find(b'\x00', 8)
        filename = remaining[8:nul].decode('ascii', errors='replace') if nul > 8 else ""
        entries.append({'name': filename, 'offset': file_offset, 'size': file_size})

    return data_start, entries

def extract_dxbc(pak_data, data_start, entry):
    """Strip SDRB headers to extract raw DXBC."""
    abs_offset = data_start + entry['offset']
    file_data = pak_data[abs_offset:abs_offset + entry['size']]

    # Skip MANAGEDFILE_DATA + BLOCK_USED_IN_ENGINE headers
    dxbc_start = file_data.find(b'DXBC')
    if dxbc_start >= 0:
        return file_data[dxbc_start:]
    return None

def main():
    pak_path = sys.argv[1]
    output_dir = sys.argv[2] or "./extracted_shaders"
    os.makedirs(f"{output_dir}/dxbc_raw", exist_ok=True)
    os.makedirs(f"{output_dir}/disassembled", exist_ok=True)

    data = open(pak_path, 'rb').read()
    data_start, entries = parse_pak_toc(data)

    extracted = 0
    for entry in entries:
        dxbc = extract_dxbc(data, data_start, entry)
        if dxbc and len(dxbc) > 64:
            clean = entry['name'].replace(':', '_').replace('/', '_')
            open(f"{output_dir}/dxbc_raw/{clean}.dxbc", 'wb').write(dxbc)
            extracted += 1

    print(f"Extracted {extracted} shaders from {len(entries)} entries")

if __name__ == '__main__':
    main()

DXBC Disassembly

For quick inspection of extracted DXBC files, use Microsoft's DXC:

bash

# Disassemble to DXBC ASM (text format)
dxc -dumpbin shader.dxbc -Fc output.asm

# Or use the standalone DXBC disassembler from Windows SDK
dxbcdisasm shader.dxbc

For programmatic disassembly (Python), the full DXBC bytecode decoder from the Warframe extraction covers:

• Opcode decoding: 180+ SM4/SM5 instructions (add, mad, mul, sample, dp4, etc.)
• Operand parsing: Register types (temp, input, output, imm), swizzle masks, write masks
• Signature parsing: ISGN/OSGN semantic names (POSITION, TEXCOORD, SV_TARGET)
• Resource definitions: Constant buffer bindings (cbuffer/register(b#)), texture bindings (Texture2D/register(t#))
• Statistics extraction: Instruction count, temp register count, texture loads

DXBC Opcode Quick Reference

The most common opcodes found in game shaders:

Opcode	Name	Category
0x31	mad	Arithmetic (multiply-add)
0x34	mul	Arithmetic
0x00	add	Arithmetic
0x42	sample	Texture sampling
0x45	sample_l	Texture with LOD
0x43	sample_c	Texture with comparison
0x10	dp4	Dot product (4-component)
0x0E	dp2	Dot product (2-component)
0x0F	dp3	Dot product (3-component)
0x4B	sqrt	Math
0x41	rsq	Math (reciprocal sqrt)
0x18	exp	Math
0x2E	log	Math
0x4A	sin	Trig
0x1B	ftou	Conversion (float to uint)
0x2A	itof	Conversion (int to float)
0x33	max / 0x32	min
0x19	frc	Fractional
0x0C	discard	Flow control
0x3A	ret	Flow control
0x2F	loop / 0x15	endloop
0x5A	dcl_constantbuffer	Declaration
0x59	dcl_resource	Declaration
0x5B	dcl_sampler	Declaration

Register Types in DXBC

Register	Name	Usage
r#	Temp register	Temporary computation results
v#	Input register	Vertex inputs / interpolators
o#	Output register	Vertex outputs / color outputs
immcb#	Imm constant buffer	Inline constants (cb0-cb15)
icb	Immediate constant buffer	Literal values embedded in shader
x#	Indexable temp	Array-indexable temporaries
null	Null register	Discarded results
id#	Instance ID	Geometry shader instance
s#	Sampler	Sampler state binding
t#	Texture	Shader resource view

Tips for Unknown PAK Formats

When facing an unknown PAK format, follow this systematic approach:

1. Hex dump the first 1KB to look for patterns, magic strings, and structure
2. Search for DXBC to locate shader bytecode and work backwards to find the TOC entries that reference those offsets
3. Look for filename strings near the DXBC locations (filenames are usually adjacent to offset/size metadata)
4. Count patterns to verify your header interpretation (entry count should match the number of delimiter repetitions)
5. Validate by extraction: Extract a candidate file and verify the first 4 bytes are DXBC (0x44, 0x58, 0x42, 0x43)
6. Handle empty entries: Some games use placeholder files (size < 64 bytes or all zeros) - skip them
7. Look for wrapper headers: Many engines wrap DXBC with custom headers (MANAGEDFILE_DATA, BLOCK_USED_IN_ENGINE, etc.) - use find(b'DXBC') to locate the real start

Real-World Results (Warframe Extraction)

Metric	Value
Total PAK entries	713
Successfully extracted	678 shaders
Empty/placeholder	35 entries
Vertex shaders (vsh)	226
Pixel shaders (psh)	452
Total bytecode	2.7 MB
Total instructions	54,944
Largest shader	uberpost.psh_63 (398 instructions, 14120 bytes)
Shader categories	28 (anim2d, artparticle, envmesh, uberpost, etc.)
Largest category	envmesh (348 shaders, 1375 KB)

---

Workflows

Creating Shaders

1. Identify target platform → determine language
2. Select shader type: vertex (geometry transform), fragment (pixel color), compute (parallel compute)
3. Use appropriate template from below
4. Define inputs (attributes, uniforms, varyings)
5. Implement main function with correct semantics

Analyzing Shaders

Detect shader type from content:

• SV_Position output / gl_Position assignment → Vertex
• SV_TARGET output / gl_FragColor / out vec4 → Fragment
• numthreads / local_size_x / @compute → Compute

Converting Shaders

1. Identify source language and shader type
2. Apply type conversions (see Type Mapping tables)
3. Convert function calls (see Intrinsic Functions tables)
4. Translate semantics (see Semantic Mapping tables)
5. Adjust entry point syntax
6. Add language-specific headers/directives
7. Handle platform differences (coordinate systems, matrix layout)

Performance Analysis Workflow

1. Write initial shader code
2. Run through target API (OpenGL/Vulkan)
3. Extract compiled shader from NVIDIA cache
4. Disassemble with nvdisasm
5. Analyze instruction counts
6. Identify STL/LDL hotspots
7. Optimize source code
8. Re-extract and compare

---

Practical Patterns (Copy-Paste Ready)

Noise Functions

Value Noise (2D)

glsl

float hash(vec2 p) {
    return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453);
}

float valueNoise(vec2 p) {
    vec2 i = floor(p);
    vec2 f = fract(p);
    f = f * f * (3.0 - 2.0 * f); // Smoothstep
    
    float a = hash(i);
    float b = hash(i + vec2(1.0, 0.0));
    float c = hash(i + vec2(0.0, 1.0));
    float d = hash(i + vec2(1.0, 1.0));
    
    return mix(mix(a, b, f.x), mix(c, d, f.x), f.y);
}

Perlin Noise (2D)

glsl

vec2 hash22(vec2 p) {
    p = vec2(dot(p, vec2(127.1, 311.7)), dot(p, vec2(269.5, 183.3)));
    return -1.0 + 2.0 * fract(sin(p) * 43758.5453);
}

float perlinNoise(vec2 p) {
    vec2 i = floor(p);
    vec2 f = fract(p);
    f = f * f * (3.0 - 2.0 * f);
    
    float a = dot(hash22(i), f - vec2(0.0, 0.0));
    float b = dot(hash22(i + vec2(1.0, 0.0)), f - vec2(1.0, 0.0));
    float c = dot(hash22(i + vec2(0.0, 1.0)), f - vec2(0.0, 1.0));
    float d = dot(hash22(i + vec2(1.0, 1.0)), f - vec2(1.0, 1.0));
    
    return mix(mix(a, b, f.x), mix(c, d, f.x), f.y) * 0.5 + 0.5;
}

Fractal Brownian Motion (FBM)

glsl

float fbm(vec2 p, int octaves) {
    float value = 0.0;
    float amplitude = 0.5;
    float frequency = 1.0;
    
    for (int i = 0; i < octaves; i++) {
        value += amplitude * perlinNoise(p * frequency);
        amplitude *= 0.5;
        frequency *= 2.0;
    }
    return value;
}

Voronoi/Cellular Noise

glsl

vec2 voronoi(vec2 p) {
    vec2 n = floor(p);
    vec2 f = fract(p);
    
    float minDist = 1.0;
    float secondMin = 1.0;
    
    for (int j = -1; j <= 1; j++) {
        for (int i = -1; i <= 1; i++) {
            vec2 neighbor = vec2(float(i), float(j));
            vec2 point = neighbor + hash(n + neighbor) - f;
            float dist = length(point);
            
            if (dist < minDist) {
                secondMin = minDist;
                minDist = dist;
            } else if (dist < secondMin) {
                secondMin = dist;
            }
        }
    }
    return vec2(minDist, secondMin); // (distance, edge)
}

---

Lighting Models

Lambert (Diffuse Only)

glsl

float lambert(vec3 normal, vec3 lightDir) {
    return max(dot(normal, lightDir), 0.0);
}

Blinn-Phong

glsl

vec3 blinnPhong(vec3 normal, vec3 lightDir, vec3 viewDir, 
                vec3 albedo, vec3 specColor, float shininess) {
    vec3 halfDir = normalize(lightDir + viewDir);
    float NdotL = max(dot(normal, lightDir), 0.0);
    float NdotH = max(dot(normal, halfDir), 0.0);
    float specular = pow(NdotH, shininess);
    return albedo * NdotL + specColor * specular;
}

Fresnel (Schlick Approximation)

glsl

vec3 fresnelSchlick(float cosTheta, vec3 F0) {
    return F0 + (1.0 - F0) * pow(1.0 - cosTheta, 5.0);
}

vec3 fresnelSchlickRoughness(float cosTheta, vec3 F0, float roughness) {
    return F0 + (max(vec3(1.0 - roughness), F0) - F0) * pow(1.0 - cosTheta, 5.0);
}

GGX/Trowbridge-Reitz (Normal Distribution)

glsl

const float PI = 3.14159265359;

float distributionGGX(vec3 N, vec3 H, float roughness) {
    float a = roughness * roughness;
    float a2 = a * a;
    float NdotH = max(dot(N, H), 0.0);
    float NdotH2 = NdotH * NdotH;
    float denom = (NdotH2 * (a2 - 1.0) + 1.0);
    denom = PI * denom * denom;
    return a2 / denom;
}

Full PBR (Cook-Torrance BRDF)

glsl

float geometrySchlickGGX(float NdotV, float roughness) {
    float r = (roughness + 1.0);
    float k = (r * r) / 8.0;
    return NdotV / (NdotV * (1.0 - k) + k);
}

float geometrySmith(vec3 N, vec3 V, vec3 L, float roughness) {
    float NdotV = max(dot(N, V), 0.0);
    float NdotL = max(dot(N, L), 0.0);
    return geometrySchlickGGX(NdotV, roughness) * geometrySchlickGGX(NdotL, roughness);
}

vec3 pbrBRDF(vec3 N, vec3 V, vec3 L, vec3 albedo, float metallic, float roughness, vec3 lightColor) {
    vec3 H = normalize(V + L);
    vec3 F0 = mix(vec3(0.04), albedo, metallic);
    
    float NDF = distributionGGX(N, H, roughness);
    float G = geometrySmith(N, V, L, roughness);
    vec3 F = fresnelSchlick(max(dot(H, V), 0.0), F0);
    
    vec3 specular = (NDF * G * F) / (4.0 * max(dot(N, V), 0.0) * max(dot(N, L), 0.0) + 0.0001);
    vec3 kD = (1.0 - F) * (1.0 - metallic);
    
    return (kD * albedo / PI + specular) * lightColor * max(dot(N, L), 0.0);
}

---

GPU Performance Optimization

Cardinal Rule

Every optimization must produce visually identical output. If you can't prove the math is equivalent, don't suggest the change. "Close enough" is not acceptable for aesthetic shaders.

---

Optimization Validation Methodology

CRITICAL: Before suggesting any function replacement or algebraic simplification, you MUST verify mathematical equivalence through testing. A replacement is only valid if the resulting equation produces equal values (for exact replacements) or very close approximation (for approximations) across the expected input range.

Validation Requirements

For every function replacement suggestion, you must:

1. Identify all variables in both the original and replacement expressions
2. Test with at least 3 different values for each variable
3. Verify results match within acceptable tolerance
4. Document any edge cases or domain restrictions

Tolerance Thresholds

Replacement Type	Maximum Acceptable Error	Notes
Exact mathematical equivalence	0 (bit-identical)	Must be provably identical
Very close approximation	< 0.001 relative error	For visual output, imperceptible difference
Approximation	< 0.01 relative error	Requires explicit user consent

Test Value Selection

When testing replacements, select test values that cover:

• Typical values: Common use case inputs (e.g., 0.5 for normalized values)
• Boundary values: Edge of valid domain (e.g., 0.0, 1.0 for colors)
• Edge cases: Potential problem areas (e.g., negative values, very small/large values)

Minimum test values per variable: 3

hlsl

// Example: Testing pow(x, 2.0) → x * x
// Variables: x
// Test values: x = 0.5, x = 2.0, x = -1.5

// Test 1: x = 0.5
pow(0.5, 2.0) = 0.25
0.5 * 0.5     = 0.25  ✓ MATCH

// Test 2: x = 2.0
pow(2.0, 2.0) = 4.0
2.0 * 2.0     = 4.0  ✓ MATCH

// Test 3: x = -1.5
pow(-1.5, 2.0) = 2.25
-1.5 * -1.5    = 2.25  ✓ MATCH

// VERDICT: Safe replacement (exact equivalence proven)

Validated Replacement Categories

Category A: Exact Equivalence (No validation needed for standard cases)

These replacements are mathematically identical and can be applied without per-case testing:

Original	Replacement	Proof
pow(x, 2.0)	x * x	x² = x × x by definition
pow(x, 3.0)	x * x * x	x³ = x × x × x by definition
pow(x, 4.0)	x2 = x*x; x2*x2	x⁴ = (x²)² by definition
pow(x, 0.5)	sqrt(x)	x^0.5 = √x by definition (x ≥ 0)
length(v) * length(v)	dot(v, v)
abs(x) * abs(x)	x * x
1.0 - (1.0 - x)	x	1 - (1 - x) = x algebraic identity
x * 1.0	x	Multiplicative identity
x + 0.0	x	Additive identity

Category B: Close Approximation (Requires testing for each use case)

These replacements approximate the original function and require validation:

Original	Approximation	Test Required	Error Characteristic
pow(x, 2.2)	x * x * pow(x, 0.2)	Yes	Varies with x
exp(x) (	x	< 0.5)	1 + x + 0.5*x*x
sin(x) (small x)	x - x³/6	Yes	Taylor series truncation
atan(x) (	x	< 1)	x / (1 + 0.28*x²)

Category C: Context-Dependent (Requires domain analysis)

These replacements depend on input domain and context:

Original	Replacement	Validation Required
clamp(x, 0.0, 1.0)	saturate(x)	Verify x is float, GPU supports saturate
normalize(v)	Skip when	v
x / y	x * (1.0 / y)	Verify y is constant or hoisted
log(x) / log(2.0)	log2(x)	Verify x > 0

Validation Procedure Template

hlsl

// VALIDATION REPORT: [Original] → [Replacement]
// ===============================================

// Variables: [list all variables]

// Test Case 1: [variable values]
original_result = [computed value]
replacement_result = [computed value]
error = abs(original_result - replacement_result)
status = [PASS/FAIL]

// Test Case 2: [variable values]
original_result = [computed value]
replacement_result = [computed value]
error = abs(original_result - replacement_result)
status = [PASS/FAIL]

// Test Case 3: [variable values]
original_result = [computed value]
replacement_result = [computed value]
error = abs(original_result - replacement_result)
status = [PASS/FAIL]

// VERDICT: [APPROVED/REJECTED/NEEDS_MORE_TESTING]
// Notes: [any edge cases or warnings]

Example: Validating exp(x) Taylor Approximation

hlsl

// VALIDATION REPORT: exp(x) → 1 + x + 0.5*x*x (for small x)
// ==========================================================

// Claim: For |x| < 0.5, Taylor series approximation is valid

// Test Case 1: x = 0.1
exp(0.1)           = 1.105170918...
1 + 0.1 + 0.05     = 1.150000000...
error              = 0.0448 (4.48% relative error)
status             = FAIL - Error too high

// Test Case 2: x = 0.2
exp(0.2)           = 1.221402758...
1 + 0.2 + 0.02     = 1.220000000...
error              = 0.0014 (0.11% relative error)
status             = MARGINAL

// Test Case 3: x = 0.3
exp(0.3)           = 1.349858808...
1 + 0.3 + 0.045    = 1.345000000...
error              = 0.00486 (0.36% relative error)
status             = MARGINAL

// VERDICT: REJECTED for precision-critical code
// The 2nd-order Taylor series has significant error even for small x.
// Recommend using 3rd-order: 1 + x + 0.5*x² + x³/6 for |x| < 0.5

Example: Validating sin(x) Small Angle Approximation

hlsl

// VALIDATION REPORT: sin(x) → x - x³/6 (for small x in radians)
// ==============================================================

// Test Case 1: x = 0.1 radians
sin(0.1)           = 0.099833417...
0.1 - 0.001/6      = 0.099833333...
error              = 0.000000084 (0.00008% relative error)
status             = PASS - Excellent approximation

// Test Case 2: x = 0.3 radians
sin(0.3)           = 0.295520207...
0.3 - 0.027/6      = 0.295500000...
error              = 0.000020207 (0.0068% relative error)
status             = PASS - Very good approximation

// Test Case 3: x = 0.5 radians
sin(0.5)           = 0.479425539...
0.5 - 0.125/6      = 0.479166667...
error              = 0.000258872 (0.054% relative error)
status             = PASS - Good approximation for visual use

// VERDICT: APPROVED for |x| < 0.5 radians with visual tolerance
// Error remains below 0.1% for angles up to ~28 degrees
// WARNING: Do not use for angles > 0.5 radians without additional terms

---

Performance Context

At high frame rates (120-240fps) on high-resolution displays (1440p+), every pixel shader instruction runs hundreds of millions of times per second. Even saving one ALU instruction matters. At 240fps on 1440p with half the overlay visible: ~885M pixel shader executions per second (3840×1600×240÷2).

1. Transcendental Optimizations (Highest Priority)

Transcendental functions (sin, cos, atan2, exp, log, pow) are the most expensive GPU instructions.

Sin/Cos Optimization

Paired sin/cos of the same angle → Use sincos:

hlsl

// BEFORE — 2 transcendentals
float s = sin(angle);
float c = cos(angle);

// AFTER — 1 intrinsic (HLSL/MSL)
float s, c;
sincos(angle, s, c);

// GLSL equivalent
float s = sin(angle);
float c = cos(angle);
// No sincos in GLSL, but still hoist repeated calls

Repeated sin/cos calls with the same argument → Hoist to local variable:

hlsl

// BEFORE — sin(time * 0.1) computed 3 times
x += sin(time * 0.1) * 2.0;
y += sin(time * 0.1) * 3.0;
z += sin(time * 0.1);

// AFTER — computed once
float st = sin(time * 0.1);
x += st * 2.0;
y += st * 3.0;
z += st;

Power Function Optimization

IMPORTANT: Power function replacements fall into two categories:

Pattern	Replacement	Validation Status	Requirements
pow(x, 2.0)	x * x	✅ VALIDATED	Exact equivalence - always safe
pow(x, 0.5)	sqrt(x)	✅ VALIDATED	Exact equivalence for x ≥ 0
pow(x, 3.0)	x * x * x	✅ VALIDATED	Exact equivalence - always safe
pow(x, 4.0)	x2 = x * x; x2 * x2	✅ VALIDATED	Exact equivalence - always safe
pow(x, 2.2)	Various approximations	⚠️ NEEDS TESTING	Test 3+ values before use

hlsl

// VALIDATED REPLACEMENT: pow(x, 2.0) → x * x
// Proof: By definition, x² = x × x
// Test values: x = 0.5, 2.0, -1.5 → All match exactly

// BEFORE — transcendental
float brightness = pow(color, 2.0);

// AFTER — ALU only (SAFE)
float brightness = color * color;

hlsl

// APPROXIMATION REQUIRES TESTING: pow(color, 2.2) approximations
// The following are approximations, not exact replacements:

// For gamma correction, pow(x, 1.0/2.2):
// BEFORE
float gamma = pow(color, 1.0/2.2);

// AFTER — faster but approximate
float gamma = sqrt(color); // gamma 2.0 (different from 2.2!)

// VALIDATION for gamma 2.0 vs 2.2:
// Test Case 1: color = 0.5
// pow(0.5, 1/2.2) = 0.730
// sqrt(0.5)       = 0.707  (3.2% error)
// VERDICT: Significant difference — may be visually noticeable

// If closer approximation needed:
float gamma = sqrt(sqrt(color * color * color)); // gamma ~2.17
// Test: pow(0.5, 1/2.2) = 0.730, approx = 0.741 (1.5% error)
// BETTER but still approximate — test in context!

Other Transcendental Patterns

hlsl

// VALIDATED: log(x) / log(2.0) → log2(x)
// Proof: log₂(x) = ln(x)/ln(2) by change of base formula
// BEFORE
float result = log(x) / log(2.0);

// AFTER (SAFE for x > 0)
float result = log2(x);  // Single instruction

hlsl

// APPROXIMATION: exp(x) Taylor series
// BEFORE
float result = exp(x);

// AFTER (for |x| < 1, requires testing)
float result = 1.0 + x + 0.5 * x * x;

// VALIDATION REQUIRED:
// Test x = 0.5: exp(0.5) = 1.649, approx = 1.625 (1.5% error)
// Test x = 0.3: exp(0.3) = 1.350, approx = 1.345 (0.4% error)
// Test x = 1.0: exp(1.0) = 2.718, approx = 2.500 (8.0% error) — UNACCEPTABLE
// VERDICT: Only valid for |x| < 0.5 with visual tolerance

2. Normalization Optimizations

hlsl

// VALIDATED: normalize() skip when length is known
// Context: float3(cos(a), sin(a), 0.0) has unit length by trigonometric identity
float3 dir = float3(cos(a), sin(a), 0.0);  // Already unit length
// Don't: dir = normalize(dir);  // Wasteful - proven unnecessary

// VALIDATED: Repeated normalize of same vector → Hoist
// BEFORE
float3 n1 = normalize(v);
float3 n2 = normalize(v);  // Redundant

// AFTER
float3 n = normalize(v);

// VALIDATED: length(v) * length(v) → dot(v, v)
// Proof: |v|² = v·v by definition
// BEFORE
float lenSq = length(v) * length(v);  // 2 length calls (sqrt operations)

// AFTER (SAFE)
float lenSq = dot(v, v);  // No sqrt, exact equivalence

// If both length and normalized vector needed:
// BEFORE
float len = length(v);
float3 n = v / len;

// AFTER (if len actually needed)
float lenSq = dot(v, v);
float len = sqrt(lenSq);
float3 n = v * rsqrt(lenSq);  // rsqrt is single instruction

3. Loop Optimizations

Loop-Invariant Code Motion

hlsl

// BEFORE — rotation computed every iteration
for (int i = 0; i < 8; i++) {
    float2x2 rot = float2x2(cos(angle), sin(angle), -sin(angle), cos(angle));
    p = mul(p, rot);
    total += noise(p);
}

// AFTER — rotation computed once
float s, c;
sincos(angle, s, c);
float2x2 rot = float2x2(c, s, -s, c);
for (int i = 0; i < 8; i++) {
    p = mul(p, rot);
    total += noise(p);
}

Accumulator Patterns

hlsl

// Common FBM pattern
float total = 0.0;
float amp = 0.5;
float2 p = uv;
for (int i = 0; i < 6; i++) {
    total += noise(p) * amp;
    p = mul(p, float2x2(1.6, 1.2, -1.2, 1.6));  // Rotate and scale
    amp *= 0.5;
}

4. Matrix and Vector Math

Rotation Matrix Optimization

hlsl

// BEFORE — per-pixel (wasteful if angle is uniform from cbuffer)
float2x2 rot = float2x2(cos(a), sin(a), -sin(a), cos(a));

// AFTER — single sincos + construction
float s, c;
sincos(a, s, c);
float2x2 rot = float2x2(c, s, -s, c);

Note: HLSL static local variables are computed once per draw call, not per-pixel:

hlsl

// This is computed per-pixel
float2x2 getRotation(float angle) {
    return float2x2(cos(angle), sin(angle), -sin(angle), cos(angle));
}

// This is computed once (if angle is compile-time constant)
static const float2x2 rot90 = float2x2(0, 1, -1, 0);

Matrix Multiplication Order

hlsl

// HLSL matrix multiplication convention:
// Vector-matrix: mul(v, M) — v treated as row vector
// Matrix-vector: mul(M, v) — v treated as column vector

// For column-major storage (GLSL default):
float4 result = mul(M, v);  // M * v

// For row-major storage (HLSL default):
float4 result = mul(v, M);  // v * M

5. Texture Sampling Efficiency

hlsl

// Redundant samples → Hoist
// BEFORE
float4 a = tex2D(sampler, uv);
float4 b = tex2D(sampler, uv);  // Same UV!
float4 c = tex2D(sampler, uv);  // Same UV!

// AFTER
float4 tex = tex2D(sampler, uv);
float4 a = tex;
float4 b = tex;
float4 c = tex;

// Sample in divergent branch → Note but don't auto-change
// Can cause quad inefficiency on some GPUs
if (condition) {
    float4 tex = tex2D(sampler, uv);  // Potential issue
}

6. Algebraic Simplifications (With Validation Status)

Pattern	Simplification	Validation	Savings
x * 0.5 + 0.5	mad(x, 0.5, 0.5) or leave as-is	✅ Exact	Compiler usually handles
1.0 - (1.0 - x)	x	✅ Exact	2 operations → 0
a / b * c (b constant)	a * (c / b)	✅ Exact	1 divide + 1 multiply → 1 multiply
length(v) * length(v)	dot(v, v)	✅ Exact	Avoids sqrt
abs(x) * abs(x)	x * x	✅ Exact	1 abs + 1 mul → 1 mul
clamp(x, 0.0, 1.0)	saturate(x)	✅ Exact	Free on most GPUs (modifier)
smoothstep(0.0, 1.0, x)	x*x*(3.0 - 2.0*x)	✅ Exact	Same cost, explicit
frac(x / 1.0)	frac(x)	✅ Exact	No-op removal
floor(x / 1.0)	floor(x)	✅ Exact	No-op removal
x / 2.0	x * 0.5	✅ Exact	Often faster (no divide)
pow(x, 2.0)	x * x	✅ Exact	Transcendental → ALU
pow(x, 3.0)	x * x * x	✅ Exact	Transcendental → ALU
pow(x, 0.5)	sqrt(x)	✅ Exact (x≥0)	Dedicated hardware
pow(x, 2.2)	Approximation	⚠️ TEST REQUIRED	Not exact - see notes below
exp(x) (small x)	1+x+0.5x²	⚠️ TEST REQUIRED	Taylor approximation

hlsl

// EXAMPLE: Validating smoothstep equivalence
// Test Case 1: x = 0.25
smoothstep(0.0, 1.0, 0.25) = 0.15625
0.25*0.25*(3.0-2.0*0.25)   = 0.15625  ✓

// Test Case 2: x = 0.5
smoothstep(0.0, 1.0, 0.5)  = 0.5
0.5*0.5*(3.0-2.0*0.5)      = 0.5  ✓

// Test Case 3: x = 0.75
smoothstep(0.0, 1.0, 0.75) = 0.84375
0.75*0.75*(3.0-2.0*0.75)   = 0.84375  ✓

// VERDICT: Exact equivalence confirmed

7. Conversion Artifacts (GLSL → HLSL)

Issue	GLSL Original	Bad HLSL	Correct HLSL	Validation
Modulo	mod(x, 1.0)	fmod(x, 1.0)	frac(x)	⚠️ Only for positive x
Modulo (general)	mod(x, y)	fmod(x, y)	x - y * floor(x/y)	✅ Exact
Texture	texture(tex, uv)	Various	tex.Sample(samp, uv)	✅ Direct mapping
FragCoord	gl_FragCoord.xy	Various	pos.xy (from SV_Position)	✅ Direct mapping

hlsl

// VALIDATION: fmod vs frac for mod(x, 1.0)
// Test Case 1: x = 2.5
mod(2.5, 1.0) = 0.5
frac(2.5)     = 0.5  ✓

// Test Case 2: x = -0.5
mod(-0.5, 1.0) = 0.5 (GLSL behavior)
frac(-0.5)     = -0.5 (different!)  ✗

// VERDICT: frac(x) is ONLY equivalent to mod(x, 1.0) for x >= 0
// For negative x, use: x - floor(x) instead

hlsl

// fmod vs frac
// BEFORE (from mechanical conversion)
float wrap = fmod(x, 1.0);  // Expensive: involves division

// AFTER (SAFE for x >= 0)
float wrap = frac(x);  // Single instruction

// AFTER (SAFE for all x, matches GLSL mod behavior)
float wrap = x - floor(x);

// Dead code from removed features
// iMouse handling often zeroed but code still computes:
float2 mouse = float2(0.0, 0.0);  // Dead
float2 dir = normalize(mouse - uv);  // Computes garbage
// Simplify away entire dead code paths

8. Constant Folding Hints

hlsl

// static const for compile-time evaluation
static const float PI = 3.14159265;
static const float TWO_PI = 2.0 * PI;  // Computed at compile time
static const float INV_PI = 1.0 / PI;

// Literal precision
// BEFORE
float x = 3.14159265358979323846;  // Wastes parser time

// AFTER
float x = 3.14159265f;  // Only 7 significant digits in float

// Integer vs float constants
// Use 2.0 instead of 2 in float contexts to avoid implicit cast
float half_val = x / 2.0;  // Clear intent

9. Compute Shader Optimizations

hlsl

[numthreads(64, 1, 1)]
void CSMain(uint3 id : SV_DispatchThreadID)
{
    uint idx = id.x;
    if (idx >= totalElements) return;  // Guard for non-multiple-of-64

    // Early-exit checks FIRST (before expensive operations)
    if (p.life >= 1.0) return;  // Skip dead particles first

    // Radius check BEFORE computing glow/color
    if (dist > maxRadius) return;  // Skip far particles

    // Avoid redundant normalize
    // BEFORE
    float3 dir = normalize(target - pos);
    float3 dir2 = normalize(target - pos);  // Redundant!

    // AFTER
    float3 dir = normalize(target - pos);
    // Reuse 'dir'
}

Compute Shader Key Patterns

1. Early-exit ordering: Skip dead particles (life >= 1.0) as first check
2. Radius check before glow: Check distance before computing expensive color
3. Avoid redundant normalize: Cache normalized vectors
4. Dispatch thread count: Guard if (idx >= total) return; is necessary for non-multiple-of-64 buffer sizes
5. Config-driven sizing: Grid dimensions and counts may be runtime values from cbuffer

10. Optimization Validation Checklist

• Prove mathematical equivalence for all changes OR document approximation error
• Test with at least 3 different values for each variable
• Check original source if converted - some "inefficiencies" may be intentional
• Verify visual output is identical (for exact replacements)
• Respect author intent (artistic choices in pow curves, etc.)
• Mark uncertain cases as "needs visual verification"
• Document any domain restrictions (e.g., "valid for x >= 0 only")

Optimization Assessment Format

Pattern	Affected Locations	Per-Pixel Cost Saved	Validation Status	Fix
Paired sin/cos → sincos	fire.hlsl:45, +12 more	~1 transcendental	✅ Exact	sincos(angle, s, c)
pow(x, 2.0) → x * x	glow.hlsl:78, +3 more	~1 transcendental	✅ Exact	x * x
pow(color, 2.2) → approximation	gamma.hlsl:23	~1 transcendental	⚠️ Test needed	Verify visually

---

Platform Gotchas

Coordinate System Differences

Platform	Origin	Y Direction	Depth Range
DirectX	Top-left	Y down	[0, 1]
OpenGL	Bottom-left	Y up	[-1, 1]
Vulkan	Top-left	Y down	[0, 1]
Metal	Top-left	Y down	[0, 1]
WebGL	Bottom-left	Y up	[-1, 1]

glsl

// OpenGL to DirectX UV flip
vec2 dxUV = vec2(uv.x, 1.0 - uv.y);

// DirectX to OpenGL depth mapping
float glDepth = depth * 2.0 - 1.0;

Matrix Layout

hlsl

// HLSL default: row-major
float4x4 mat;  // mat[0] is the first ROW

// GLSL default: column-major
mat4 mat;  // mat[0] is the first COLUMN

// Matrix multiplication order
// HLSL: mul(vector, matrix) - vector on left
// GLSL: matrix * vector - vector on right

Mod Function Differences

hlsl

// GLSL mod() vs HLSL fmod() behave differently for negative numbers
// GLSL: mod(-3.0, 2.0) = 1.0
// HLSL: fmod(-3.0, 2.0) = -1.0

// Portable mod for HLSL
float mod(float x, float y) {
    return x - y * floor(x / y);
}

ReShade FX Specific Gotchas

CRITICAL: ReShade FX does NOT include fmod among its intrinsic functions, unlike standard HLSL. This is a common mistake when porting HLSL shaders to ReShade.

hlsl

// WRONG - fmod does not exist in ReShade FX
float wrapped = fmod(x, 1.0);  // Compile error!

// CORRECT - Use custom helper function
float wrapped = x - floor(x);  // Equivalent to frac(x) for positive x

// CORRECT - Full GLSL-style mod implementation for ReShade
float mod(float x, float y) {
    return x - y * floor(x / y);
}

// For wrapping values (most common use case):
// Instead of: fmod(time, 1.0)
float wrapped = frac(time);  // Works for positive values

// Instead of: fmod(coord, 2.0) - for wrapping coordinates
float2 wrappedCoord = frac(coord / 2.0) * 2.0;  // Wraps to [0, 2)

ReShade FX Missing Intrinsics Reference:

Function	Standard HLSL	ReShade FX	Workaround
Modulo	fmod(x, y)	❌ Not available	x - y * floor(x / y)
Fractional wrap	fmod(x, 1.0)	❌ Not available	frac(x) (positive x only)
Remainder	% operator	❌ Not available	Custom function

Safe ReShade Mod Helper Functions:

hlsl

// Add these to your ReShade shaders when you need modulo operations

// GLSL-compatible mod (handles negative numbers correctly)
float mod(float x, float y) {
    return x - y * floor(x / y);
}
float2 mod(float2 x, float2 y) {
    return x - y * floor(x / y);
}
float3 mod(float3 x, float3 y) {
    return x - y * floor(x / y);
}
float4 mod(float4 x, float4 y) {
    return x - y * floor(x / y);
}

// For simple 0-1 wrapping (positive values only, faster)
// frac(x) is available in ReShade and equals x - floor(x)

Precision Differences

glsl

// WebGL 1.0 requires precision qualifiers
precision mediump float;  // ~16-bit
precision highp float;    // ~32-bit

// Mobile GPU precision pitfalls
// - mediump may introduce banding
// - lowp sufficient for colors (0-1 range)
// - highp needed for positions, depths

---

Troubleshooting Guide

Common Errors & Solutions

Error Message	Cause	Solution
Cannot resolve symbol	Undefined variable/function	Check spelling, includes
Type mismatch	Wrong type in expression	Match vec/mat sizes
Uninitialized variable	Variable used before set	Initialize all variables
Division by zero	Constant 0 divisor	Guard with condition

Black Screen Debug

hlsl

return float4(1, 0, 0, 1);  // If red, shader runs
return float4(normal * 0.5 + 0.5, 1);  // Visualize normals
return float4(uv, 0, 1);  // Visualize UVs
return float4(depth.rrr, 1);  // Visualize depth

NaN/Inf Detection

hlsl

bool isNaN(float x) { return x != x; }
bool isInf(float x) { return x == x * 2.0 && x != 0.0; }

float safeDiv(float a, float b) { return a / (b + 1e-6); }
float safeSqrt(float x) { return sqrt(max(0.0, x)); }
float safeAcos(float x) { return acos(clamp(x, -1.0, 1.0)); }

---

Type Mapping

Scalar Types

HLSL	GLSL	MSL	WGSL
float	float	float	f32
int	int	int	i32
uint	uint	uint	u32
bool	bool	bool	bool
half	float (ES: mediump)	half	f16
double	double	double	f64

Vector Types

HLSL	GLSL	MSL	WGSL
float2	vec2	float2	vec2<f32>
float3	vec3	float3	vec3<f32>
float4	vec4	float4	vec4<f32>
int2	ivec2	int2	vec2<i32>
int3	ivec3	int3	vec3<i32>
int4	ivec4	int4	vec4<i32>
uint2	uvec2	uint2	vec2<u32>
uint3	uvec3	uint3	vec3<u32>
uint4	uvec4	uint4	vec4<u32>
bool2	bvec2	bool2	vec2<bool>
bool3	bvec3	bool3	vec3<bool>
bool4	bvec4	bool4	vec4<bool>

Matrix Types

HLSL	GLSL	MSL	WGSL
float2x2	mat2	float2x2	mat2x2<f32>
float3x3	mat3	float3x3	mat3x3<f32>
float4x4	mat4	float4x4	mat4x4<f32>
float2x3	mat2x3	float2x3	mat2x3<f32>
float3x2	mat3x2	float3x2	mat3x2<f32>
float3x4	mat3x4	float3x4	mat3x4<f32>
float4x3	mat4x3	float4x3	mat4x3<f32>

Texture/Sampler Types

HLSL	GLSL	MSL	WGSL
Texture1D	sampler1D	texture1d<float>	texture_1d<f32>
Texture2D	sampler2D	texture2d<float>	texture_2d<f32>
Texture3D	sampler3D	texture3d<float>	texture_3d<f32>
TextureCube	samplerCube	texturecube<float>	texture_cube<f32>
Texture2DArray	sampler2DArray	texture2d_array<float>	texture_2d_array<f32>
RWTexture2D<float4>	image2D	texture2d<float,access::write>	texture_storage_2d<rgba32float,write>

---

Intrinsic Functions

Math Functions

Operation	HLSL	GLSL	MSL	WGSL
Absolute	abs(x)	abs(x)	abs(x)	abs(x)
Sign	sign(x)	sign(x)	sign(x)	sign(x)
Floor	floor(x)	floor(x)	floor(x)	floor(x)
Ceil	ceil(x)	ceil(x)	ceil(x)	ceil(x)
Round	round(x)	round(x)	round(x)	round(x)
Fractional	frac(x)	fract(x)	fract(x)	fract(x)
Modulo	fmod(a,b)	mod(a,b)	fmod(a,b)	a % b
Min	min(a,b)	min(a,b)	min(a,b)	min(a,b)
Max	max(a,b)	max(a,b)	max(a,b)	max(a,b)
Clamp	clamp(x,a,b)	clamp(x,a,b)	clamp(x,a,b)	clamp(x,a,b)
Saturate	saturate(x)	clamp(x,0,1)	saturate(x)	clamp(x,0.0,1.0)
Linear interp	lerp(a,b,t)	mix(a,b,t)	mix(a,b,t)	mix(a,b,t)
Smoothstep	smoothstep(a,b,x)	smoothstep(a,b,x)	smoothstep(a,b,x)	smoothstep(a,b,x)
Square root	sqrt(x)	sqrt(x)	sqrt(x)	sqrt(x)
Inverse sqrt	rsqrt(x)	inversesqrt(x)	rsqrt(x)	inverseSqrt(x)
Power	pow(x,y)	pow(x,y)	pow(x,y)	pow(x,y)
Exp	exp(x)	exp(x)	exp(x)	exp(x)
Log	log(x)	log(x)	log(x)	log(x)
Log2	log2(x)	log2(x)	log2(x)	log2(x)
Reciprocal	rcp(x)	1.0/x	rcp(x)	1.0/x
Mad	mad(a,b,c)	fma(a,b,c)	fma(a,b,c)	fma(a,b,c)

Trigonometric Functions

Operation	HLSL	GLSL	MSL	WGSL
Sin	sin(x)	sin(x)	sin(x)	sin(x)
Cos	cos(x)	cos(x)	cos(x)	cos(x)
Tan	tan(x)	tan(x)	tan(x)	tan(x)
Asin	asin(x)	asin(x)	asin(x)	asin(x)
Acos	acos(x)	acos(x)	acos(x)	acos(x)
Atan2	atan2(y,x)	atan(y,x)	atan2(y,x)	atan2(y,x)
SinCos	sincos(x,s,c)	s=sin(x);c=cos(x)	sincos(x,s,c)	s=sin(x);c=cos(x)
Degrees	degrees(x)	degrees(x)	degrees(x)	degrees(x)
Radians	radians(x)	radians(x)	radians(x)	radians(x)

Derivative Functions

Operation	HLSL	GLSL	MSL	WGSL
Derivative X	ddx(x)	dFdx(x)	dfdx(x)	dpdx(x)
Derivative Y	ddy(x)	dFdy(x)	dfdy(x)	dpdy(x)
Fwidth	fwidth(x)	fwidth(x)	fwidth(x)	fwidth(x)

Vector/Matrix Operations

Operation	HLSL	GLSL	MSL	WGSL
Dot	dot(a,b)	dot(a,b)	dot(a,b)	dot(a,b)
Cross	cross(a,b)	cross(a,b)	cross(a,b)	cross(a,b)
Normalize	normalize(v)	normalize(v)	normalize(v)	normalize(v)
Length	length(v)	length(v)	length(v)	length(v)
Distance	distance(a,b)	distance(a,b)	distance(a,b)	distance(a,b)
Reflect	reflect(i,n)	reflect(i,n)	reflect(i,n)	reflect(i,n)
Refract	refract(i,n,r)	refract(i,n,r)	refract(i,n,r)	refract(i,n,r)
Transpose	transpose(m)	transpose(m)	transpose(m)	transpose(m)
Determinant	determinant(m)	determinant(m)	determinant(m)	determinant(m)
Inverse	inverse(m)	inverse(m)	inverse(m)	inverse(m)

Texture Sampling

Operation	HLSL	GLSL	MSL	WGSL
Sample	tex.Sample(s,uv)	texture(tex,uv)	tex.sample(s,uv)	textureSample(tex,s,uv)
Sample LOD	tex.SampleLevel(s,uv,lod)	textureLod(tex,uv,lod)	tex.sample(s,uv,level(lod))	textureSampleLevel(tex,s,uv,lod)
Sample Grad	tex.SampleGrad(s,uv,dx,dy)	textureGrad(tex,uv,dx,dy)	tex.sample(s,uv,gradient2d(dx,dy))	textureSampleGrad(tex,s,uv,dx,dy)
Fetch	tex.Load(pos)	texelFetch(tex,pos,lod)	tex.read(pos)	textureLoad(tex,pos)
Store	tex[pos] = val	imageStore(img,pos,val)	tex.write(val,pos)	textureStore(tex,pos,val)
Size	tex.GetDimensions(w,h)	textureSize(tex,lod)	tex.get_width()	textureDimensions(tex)

Bit/Cast Functions

Operation	HLSL	GLSL	MSL	WGSL
As float	asfloat(x)	intBitsToFloat(x)	as_type<float>(x)	bitcast<f32>(x)
As int	asint(x)	floatBitsToInt(x)	as_type<int>(x)	bitcast<i32>(x)
As uint	asuint(x)	floatBitsToUint(x)	as_type<uint>(x)	bitcast<u32>(x)
Count bits	countbits(x)	bitCount(x)	popcount(x)	countTrailingZeros(x)
Reverse bits	reversebits(x)	bitfieldReverse(x)	reverse_bits(x)	reverseBits(x)

---

Semantic Mapping

Vertex Shader Semantics

Meaning	HLSL	GLSL	MSL	WGSL
Position output	SV_Position	gl_Position	[[position]]	@builtin(position)
Position input	POSITION	layout(location=0) in	[[attribute(0)]]	@location(0)
Normal	NORMAL	layout(location=N) in	[[attribute(N)]]	@location(N)
Vertex ID	SV_VertexID	gl_VertexID	[[vertex_id]]	@builtin(vertex_index)
Instance ID	SV_InstanceID	gl_InstanceID	[[instance_id]]	@builtin(instance_index)

Fragment Shader Semantics

Meaning	HLSL	GLSL	MSL	WGSL
Color output	SV_Target	layout(location=0) out	[[color(0)]]	@location(0)
Depth output	SV_Depth	gl_FragDepth	[[depth(any)]]	@builtin(frag_depth)
Front facing	SV_IsFrontFace	gl_FrontFacing	[[front_facing]]	@builtin(front_facing)

Compute Shader Semantics

Meaning	HLSL	GLSL	MSL	WGSL
Global thread ID	SV_DispatchThreadID	gl_GlobalInvocationID	[[thread_position_in_grid]]	@builtin(global_invocation_id)
Local thread ID	SV_GroupThreadID	gl_LocalInvocationID	[[thread_position_in_threadgroup]]	@builtin(local_invocation_id)
Group ID	SV_GroupID	gl_WorkGroupID	[[threadgroup_position_in_grid]]	@builtin(workgroup_id)

---

Buffer Binding

HLSL

hlsl

cbuffer CameraBuffer : register(b0) { float4x4 View; float4x4 Proj; }
Texture2D diffuseTex : register(t0);
SamplerState linearSampler : register(s0);
RWStructuredBuffer<float> outputBuffer : register(u0);

GLSL

glsl

layout(std140, binding = 0) uniform CameraBuffer { mat4 View; mat4 Proj; };
layout(std430, binding = 0) buffer OutputBuffer { float data[]; };
uniform sampler2D diffuseTex;

MSL

metal

constant CameraBuffer& cam [[buffer(0)]];
texture2d<float> diffuseTex [[texture(0)]];
sampler linearSampler [[sampler(0)]];
device float* outputBuffer [[buffer(0)]];

WGSL

wgsl

@group(0) @binding(0) var<uniform> camera: CameraBuffer;
@group(0) @binding(1) var diffuseTex: texture_2d<f32>;
@group(0) @binding(2) var linearSampler: sampler;
@group(0) @binding(3) var<storage, read_write> outputBuffer: array<f32>;

---

Complete Templates

HLSL Vertex + Pixel Shader

hlsl

cbuffer TransformBuffer : register(b0) {
    float4x4 World;
    float4x4 View;
    float4x4 Projection;
};

struct VSInput {
    float3 position : POSITION;
    float3 normal : NORMAL;
    float2 texcoord : TEXCOORD0;
};

struct VSOutput {
    float4 position : SV_Position;
    float3 normal : NORMAL;
    float2 texcoord : TEXCOORD0;
};

VSOutput VSMain(VSInput input) {
    VSOutput output;
    float4 worldPos = mul(float4(input.position, 1.0), World);
    output.position = mul(mul(worldPos, View), Projection);
    output.normal = mul(input.normal, (float3x3)World);
    output.texcoord = input.texcoord;
    return output;
}

Texture2D diffuseTex : register(t0);
SamplerState sampler0 : register(s0);

float4 PSMain(VSOutput input) : SV_Target {
    return diffuseTex.Sample(sampler0, input.texcoord);
}

HLSL Compute Shader

hlsl

RWTexture2D<float4> OutputTex : register(u0);
Texture2D<float4> InputTex : register(t0);

[numthreads(8, 8, 1)]
void CSMain(uint3 id : SV_DispatchThreadID) {
    uint width, height;
    InputTex.GetDimensions(width, height);
    if (id.x >= width || id.y >= height) return;
    
    float4 color = InputTex[id.xy];
    float gray = dot(color.rgb, float3(0.299, 0.587, 0.114));
    OutputTex[id.xy] = float4(gray, gray, gray, color.a);
}

GLSL Vertex + Fragment Shader

glsl

#version 450

layout(location = 0) in vec3 position;
layout(location = 1) in vec3 normal;
layout(location = 2) in vec2 texcoord;

layout(location = 0) out vec3 v_normal;
layout(location = 1) out vec2 v_texcoord;

layout(std140, binding = 0) uniform TransformBuffer {
    mat4 World;
    mat4 View;
    mat4 Projection;
};

void main() {
    vec4 worldPos = World * vec4(position, 1.0);
    gl_Position = Projection * View * worldPos;
    v_normal = mat3(World) * normal;
    v_texcoord = texcoord;
}

// Fragment Shader
#version 450

layout(location = 0) in vec3 v_normal;
layout(location = 1) in vec2 v_texcoord;
layout(location = 0) out vec4 fragColor;

layout(binding = 0) uniform sampler2D diffuseTex;

void main() {
    fragColor = texture(diffuseTex, v_texcoord);
}

MSL Vertex + Fragment Shader

metal

#include <metal_stdlib>
using namespace metal;

struct VSInput {
    float4 position [[attribute(0)]];
    float3 normal [[attribute(1)]];
    float2 texcoord [[attribute(2)]];
};

struct VSOutput {
    float4 position [[position]];
    float3 normal;
    float2 texcoord;
};

struct TransformBuffer {
    float4x4 World;
    float4x4 View;
    float4x4 Projection;
};

vertex VSOutput vertex_main(
    VSInput input [[stage_in]],
    constant TransformBuffer& transform [[buffer(0)]]
) {
    VSOutput output;
    float4 worldPos = transform.World * input.position;
    output.position = transform.Projection * transform.View * worldPos;
    output.normal = (transform.World * float4(input.normal, 0.0)).xyz;
    output.texcoord = input.texcoord;
    return output;
}

fragment float4 fragment_main(
    VSOutput input [[stage_in]],
    texture2d<float> diffuseTex [[texture(0)]],
    sampler sampler0 [[sampler(0)]]
) {
    return diffuseTex.sample(sampler0, input.texcoord);
}

WGSL Vertex + Fragment Shader

wgsl

struct VSInput {
    @location(0) position: vec3<f32>,
    @location(1) normal: vec3<f32>,
    @location(2) texcoord: vec2<f32>,
}

struct VSOutput {
    @builtin(position) position: vec4<f32>,
    @location(0) normal: vec3<f32>,
    @location(1) texcoord: vec2<f32>,
}

struct TransformBuffer {
    World: mat4x4<f32>,
    View: mat4x4<f32>,
    Projection: mat4x4<f32>,
}

@group(0) @binding(0) var<uniform> transform: TransformBuffer;

@vertex
fn vs_main(input: VSInput) -> VSOutput {
    var output: VSOutput;
    let worldPos = transform.World * vec4<f32>(input.position, 1.0);
    output.position = transform.Projection * transform.View * worldPos;
    output.normal = (transform.World * vec4<f32>(input.normal, 0.0)).xyz;
    output.texcoord = input.texcoord;
    return output;
}

@group(0) @binding(1) var diffuseTex: texture_2d<f32>;
@group(0) @binding(2) var sampler0: sampler;

@fragment
fn fs_main(input: VSOutput) -> @location(0) vec4<f32> {
    return textureSample(diffuseTex, sampler0, input.texcoord);
}

---

ReShade FX Reference

ReShade FX is based on DX9-style HLSL with extensions for post-processing effects.

Preprocessor Macros

Macro	Description
__FILE__	Current file path
__FILE_NAME__	Current file name without path
__FILE_STEM__	Current file name without extension and path
__LINE__	Current line number
__RESHADE__	ReShade version (MAJOR10000 + MINOR100 + REVISION)
__APPLICATION__	32-bit Fnv1a hash of executable name
__VENDOR__	GPU vendor ID (0x10de=NVIDIA, 0x1002=AMD, 0x8086=Intel)
__DEVICE__	Device ID
__RENDERER__	Graphics API (0x9000=D3D9, 0xa000=D3D10, 0xb000=D3D11, 0xc000=D3D12, 0x10000=OpenGL, 0x20000=Vulkan)
BUFFER_WIDTH	Backbuffer width in pixels
BUFFER_HEIGHT	Backbuffer height in pixels
BUFFER_RCP_WIDTH	Reciprocal width (1.0 / BUFFER_WIDTH)
BUFFER_RCP_HEIGHT	Reciprocal height (1.0 / BUFFER_HEIGHT)
BUFFER_COLOR_FORMAT	Backbuffer texture format
BUFFER_COLOR_BIT_DEPTH	Color bit depth (8, 10, or 16)
BUFFER_COLOR_SPACE	Color space (0=unknown, 1=sRGB, 2=scRGB, 3=HDR10 ST2084, 4=HDR10 HLG)
ADDON_[NAME]	Defined for each enabled addon (e.g., ADDON_GENERIC_DEPTH)

hlsl

// Prevent preprocessor defines from appearing in UI (prefix with underscore or <8 chars)
#ifndef _INTERNAL_DEFINE
    #define _INTERNAL_DEFINE 0
#endif

// Disable shader optimization for debugging
#pragma reshade skipoptimization

Special Texture Semantics

hlsl

texture2D texColor : COLOR;   // Backbuffer contents (read-only)
texture2D texDepth : DEPTH;   // Game's depth buffer (read-only)

Texture Declaration

hlsl

texture2D texTarget
{
    Width = BUFFER_WIDTH / 2;   // Default: 1
    Height = BUFFER_HEIGHT / 2; // Default: 1
    MipLevels = 1;              // Default: 1
    Format = RGBA8;             // Default: RGBA8
    // Available: R8, R16, R16F, R32F, R32I, R32U
    //            RG8, RG16, RG16F, RG32F
    //            RGBA8, RGBA16, RGBA16F, RGBA32F
    //            RGB10A2, R11G11B10F
};

// Load image from file
texture2D imageTex < source = "path/to/image.png"; > { Width = 512; Height = 512; };

// Pooled textures (memory sharing)
texture2D myTex1 < pooled = true; > { Width = 100; Height = 100; Format = RGBA8; };

Sampler Declaration

hlsl

sampler2D samplerColor
{
    Texture = texColor;       // Required: texture to sample
    AddressU = CLAMP;         // CLAMP, MIRROR, WRAP, BORDER
    AddressV = CLAMP;
    AddressW = CLAMP;
    MagFilter = LINEAR;       // POINT, LINEAR, ANISOTROPIC
    MinFilter = LINEAR;
    MipFilter = LINEAR;
    MinLOD = 0.0f;
    MaxLOD = 1000.0f;
    MipLODBias = 0.0f;
    SRGBTexture = false;      // Convert to linear on sample
};

// Access backbuffer via ReShade namespace
sampler2D BackBuffer { Texture = ReShade::BackBuffer; };

Storage Objects (Compute Shaders)

hlsl

storage2D storageTarget
{
    Texture = texTarget;
    MipLevel = 0;
};

// Integer storage
storage3D<int> storageVolume { Texture = texIntegerVolume; };

Uniform Variables with UI Annotations

hlsl

// Slider
uniform float Brightness <
    ui_type = "slider";
    ui_min = -1.0; ui_max = 1.0;
    ui_label = "Brightness";
    ui_tooltip = "Adjusts overall brightness";
    ui_units = "cd/m²";
> = 0.0;

// Drag (similar to slider)
uniform float Intensity <
    ui_type = "drag";
    ui_min = 0.0; ui_max = 2.0;
    ui_step = 0.01;
> = 1.0;

// Combo box
uniform int BlendMode <
    ui_type = "combo";
    ui_items = "Normal\0Multiply\0Screen\0Overlay\0";
    ui_label = "Blend Mode";
> = 0;

// Radio buttons
uniform int Quality <
    ui_type = "radio";
    ui_items = "Low\0Medium\0High\0Ultra\0";
> = 1;

// Color picker
uniform float3 TintColor <
    ui_type = "color";
    ui_label = "Tint Color";
> = float3(1.0, 1.0, 1.0);

// Button
uniform bool ResetSettings <
    ui_type = "button";
    ui_label = "Reset to Defaults";
> = false;

// Hidden from UI
uniform float4 InternalData < hidden = true; >;

// Read-only display
uniform float DebugValue < noedit = true; >;

Runtime Value Sources

hlsl

uniform float frametime < source = "frametime"; >;      // MS per frame
uniform int framecount < source = "framecount"; >;      // Total frames
uniform float4 date < source = "date"; >;               // (year, month, day, time)
uniform float timer < source = "timer"; >;              // MS since start

// Ping-pong animation
uniform float2 pingpong < source = "pingpong"; min = 0; max = 10; step = 2; smoothing = 0.0; >;

// Random value
uniform int random_value < source = "random"; min = 0; max = 10; >;

// Key input
uniform bool space_bar < source = "key"; keycode = 0x20; mode = ""; >;  // mode: "", "press", "toggle"

// Mouse input
uniform bool left_click < source = "mousebutton"; keycode = 0; >;
uniform float2 mouse_pos < source = "mousepoint"; >;
uniform float2 mouse_delta < source = "mousedelta"; >;
uniform float2 mouse_wheel < source = "mousewheel"; min = 0.0; max = 10.0; > = 1.0;

// State checks
uniform bool has_depth < source = "bufready_depth"; >;
uniform bool overlay_open < source = "overlay_open"; >;
uniform bool taking_screenshot < source = "screenshot"; >;

Structs and Namespaces

hlsl

struct VSOutput {
    float4 position : SV_Position;
    float2 texcoord : TEXCOORD0;
    float3 color : COLOR0;
};

namespace MyEffects {
    namespace Utils {
        float3 RGBtoHSV(float3 rgb) { return rgb; }
    }
    float3 ProcessColor(float3 color) { return Utils::RGBtoHSV(color); }
}
// Usage: MyEffects::ProcessColor(color)

Vertex Shader (Full-Screen Quad)

hlsl

// Standard ReShade vertex shader (provided by ReShade.fxh)
void PostProcessVS(in uint id : SV_VertexID, out float4 position : SV_Position, out float2 texcoord : TEXCOORD) {
    texcoord.x = (id == 2) ? 2.0 : 0.0;
    texcoord.y = (id == 1) ? 2.0 : 0.0;
    position = float4(texcoord * float2(2, -2) + float2(-1, 1), 0, 1);
}

// Alternative with shader attribute
[shader("vertex")]
void MyVS(uint id : SV_VertexID, out float4 position : SV_Position, out float2 texcoord : TEXCOORD0) {
    // Same logic
}

Pixel Shader

hlsl

// Basic pixel shader
float3 PS_Effect(float4 vpos : SV_Position, float2 texcoord : TEXCOORD) : SV_Target {
    float3 color = tex2D(ReShade::BackBuffer, texcoord).rgb;
    return color;
}

// With shader attribute
[shader("pixel")]
void PS_Effect2(float4 vpos : SV_Position, float2 texcoord : TEXCOORD0, out float4 color : SV_Target) {
    color = tex2D(ReShade::BackBuffer, texcoord);
}

// Using discard to exclude pixels
float4 PS_DiscardExample(float4 vpos : SV_Position, float2 texcoord : TEXCOORD) : SV_Target {
    if (texcoord.x < 0.1 || texcoord.x > 0.9)
        discard;  // Abort rendering this pixel
    return tex2D(ReShade::BackBuffer, texcoord);
}

Function Parameter Qualifiers

hlsl

// in: input parameter (default, implicit)
void ProcessInput(in float3 color) { }

// out: output parameter - value filled by function
void GetUV(out float2 uv) { uv = float2(0.5, 0.5); }

// inout: both input and output
void ModifyColor(inout float3 color) { color *= 0.5; }

Flow Control Attributes

hlsl

// Branch attributes
[branch] if (condition) { }     // Force dynamic branching
[flatten] if (condition) { }    // Force flatten (no branch)

// Switch attributes
[flatten] switch (value) { }
[branch] switch (value) { }
[forcecase] switch (value) { }
[call] switch (value) { }

// Loop attributes
[unroll] for (int i = 0; i < 4; i++) { }  // Unroll loop
[loop] for (int i = 0; i < n; i++) { }    // Don't unroll
[fastopt] for (int i = 0; i < n; i++) { } // Fast optimization

Compute Shader

hlsl

groupshared int sharedMem[64];

[numthreads(8, 8, 1)]
void CS_Main(uint3 id : SV_DispatchThreadID, uint3 tid : SV_GroupThreadID) {
    // Use tex2Dstore() for writing
    tex2Dstore(storageTarget, id.xy, float4(1, 0, 0, 1));
}

Technique & Pass Definition

hlsl

technique MyEffect <
    ui_label = "My Cool Effect";
    ui_tooltip = "Description shown on hover";
    enabled = true;              // Enable by default
    enabled_in_screenshot = true;
    hidden = false;              // Show in UI
    timeout = 0;                 // Auto-disable after MS (0 = never)
>
{
    pass p0
    {
        // Primitive topology for draw call
        PrimitiveTopology = TRIANGLELIST;  // POINTLIST, LINELIST, LINESTRIP, TRIANGLELIST, TRIANGLESTRIP
        VertexCount = 3;                   // Number of vertices ReShade generates

        // Shaders
        VertexShader = PostProcessVS;
        PixelShader = PS_Effect;

        // Render targets
        RenderTarget = texTarget;        // or RenderTarget0, RenderTarget1-7
        ClearRenderTargets = false;
        GenerateMipMaps = true;

        // Blend state
        BlendEnable = false;
        BlendOp = ADD;                   // ADD, SUBTRACT, REVSUBTRACT, MIN, MAX
        BlendOpAlpha = ADD;
        SrcBlend = ONE;                  // ZERO, ONE, SRCCOLOR, SRCALPHA, INVSRCCOLOR, INVSRCALPHA
        SrcBlendAlpha = ONE;
        DestBlend = ZERO;                // ZERO, ONE, DESTCOLOR, DESTALPHA, INVDESTCOLOR, INVDESTALPHA
        DestBlendAlpha = ZERO;

        // Stencil state
        StencilEnable = false;
        StencilRef = 0;
        StencilReadMask = 0xFF;          // 0-255
        StencilWriteMask = 0xFF;
        StencilFunc = ALWAYS;            // NEVER, ALWAYS, EQUAL, NOTEQUAL, LESS, GREATER, LESSEQUAL, GREATEREQUAL
        StencilPassOp = KEEP;            // KEEP, ZERO, REPLACE, INCR, INCRSAT, DECR, DECRSAT, INVERT
        StencilFailOp = KEEP;
        StencilDepthFailOp = KEEP;       // or StencilZFail

        // Output
        SRGBWriteEnable = false;
        RenderTargetWriteMask = 0xF;     // ColorWriteEnable
    }

    pass compute_pass
    {
        ComputeShader = CS_Main<8,8,1>;   // Thread group size
        DispatchSizeX = 20;               // 20 * 8 = 160 threads in X
        DispatchSizeY = 2;                // 2 * 8 = 16 threads in Y
        DispatchSizeZ = 1;
    }
}

Pass State Reference

State	Values	Description
PrimitiveTopology	POINTLIST, LINELIST, LINESTRIP, TRIANGLELIST, TRIANGLESTRIP	Primitive type
VertexCount	1-N	Number of vertices generated
VertexShader	function name	Vertex shader entry point
PixelShader	function name	Pixel shader entry point
ComputeShader	function	Compute shader with thread group size
RenderTarget0-7	texture name	Render target textures
ClearRenderTargets	true/false	Clear to zero before rendering
GenerateMipMaps	true/false	Auto-generate mipmaps after pass
BlendEnable	true/false	Enable blending
BlendOp	ADD, SUBTRACT, REVSUBTRACT, MIN, MAX	Color blend operation
SrcBlend	ZERO, ONE, SRCCOLOR, SRCALPHA, INVSRCCOLOR, INVSRCALPHA, DESTCOLOR, DESTALPHA, INVDESTCOLOR, INVDESTALPHA	Source blend factor
DestBlend	Same as SrcBlend	Destination blend factor
StencilEnable	true/false	Enable stencil test
StencilFunc	NEVER, ALWAYS, EQUAL, NOTEQUAL, LESS, GREATER, LESSEQUAL, GREATEREQUAL	Stencil comparison
StencilPassOp	KEEP, ZERO, REPLACE, INCR, INCRSAT, DECR, DECRSAT, INVERT	Stencil pass operation
SRGBWriteEnable	true/false	Apply gamma correction
RenderTargetWriteMask	0x0-0xF	Color channel write mask

ReShade-Specific Intrinsics

Texture Sampling

hlsl

// Basic sampling
T tex1D(sampler1D s, float coords)
T tex1D(sampler1D s, float coords, int offset)
T tex2D(sampler2D s, float2 coords)
T tex2D(sampler2D s, float2 coords, int2 offset)
T tex3D(sampler3D s, float3 coords)
T tex3D(sampler3D s, float3 coords, int3 offset)

// Sample at specific LOD
T tex1Dlod(sampler1D s, float4 coords)  // coords = float4(x, 0, 0, lod)
T tex2Dlod(sampler2D s, float4 coords)  // coords = float4(x, y, 0, lod)
T tex3Dlod(sampler3D s, float4 coords)  // coords = float4(x, y, z, lod)

// Sample with gradient (explicit derivatives)
T tex1Dgrad(sampler1D s, float coords, float ddx, float ddy)
T tex2Dgrad(sampler2D s, float2 coords, float2 ddx, float2 ddy)
T tex3Dgrad(sampler3D s, float3 coords, float3 ddx, float3 ddy)

// Fetch without filtering (integer coordinates)
T tex1Dfetch(sampler1D s, int coords)
T tex1Dfetch(sampler1D s, int coords, int lod)
T tex1Dfetch(storage1D s, int coords)
T tex2Dfetch(sampler2D s, int2 coords)
T tex2Dfetch(sampler2D s, int2 coords, int lod)
T tex2Dfetch(storage2D s, int2 coords)
T tex3Dfetch(sampler3D s, int3 coords)
T tex3Dfetch(sampler3D s, int3 coords, int lod)
T tex3Dfetch(storage3D s, int3 coords)

// Gather (returns 4 samples from neighboring pixels)
float4 tex2DgatherR(sampler2D s, float2 coords)  // Gather red component
float4 tex2DgatherG(sampler2D s, float2 coords)  // Gather green component
float4 tex2DgatherB(sampler2D s, float2 coords)  // Gather blue component
float4 tex2DgatherA(sampler2D s, float2 coords)  // Gather alpha component

// Get texture dimensions
int  tex1Dsize(sampler1D s)
int  tex1Dsize(sampler1D s, int lod)
int  tex1Dsize(storage1D s)
int2 tex2Dsize(sampler2D s)
int2 tex2Dsize(sampler2D s, int lod)
int2 tex2Dsize(storage2D s)
int3 tex3Dsize(sampler3D s)
int3 tex3Dsize(sampler3D s, int lod)
int3 tex3Dsize(storage3D s)

// Store to texture (compute only)
void tex1Dstore(storage1D s, int coords, T value)
void tex2Dstore(storage2D s, int2 coords, T value)
void tex3Dstore(storage3D s, int3 coords, T value)

Synchronization

hlsl

void barrier()            // GroupMemoryBarrierWithGroupSync
void memoryBarrier()      // AllMemoryBarrier
void groupMemoryBarrier() // GroupMemoryBarrier

Atomic Operations

hlsl

// All atomics return the original value before operation
int atomicAdd(inout int dest, int value)
int atomicAdd(storage1D s, int coords, int value)
int atomicAdd(storage2D s, int2 coords, int value)
int atomicAdd(storage3D s, int3 coords, int value)

int atomicAnd(inout int dest, int value)
int atomicOr(inout int dest, int value)
int atomicXor(inout int dest, int value)
int atomicMin(inout int dest, int value)
int atomicMax(inout int dest, int value)
int atomicExchange(inout int dest, int value)
int atomicCompareExchange(inout int dest, int compare, int value)

ReShade Built-in Samplers

hlsl

ReShade::BackBuffer  // Game's rendered image
ReShade::DepthBuffer // Game's depth buffer

ReShade Standard Library Headers

ReShade.fxh - Core Header

hlsl

#include "ReShade.fxh"

// Provides:
// - Version checking: __RESHADE__ >= 30000
// - Buffer size macros: BUFFER_WIDTH, BUFFER_HEIGHT, BUFFER_RCP_WIDTH, BUFFER_RCP_HEIGHT
// - BUFFER_PIXEL_SIZE, BUFFER_SCREEN_SIZE, BUFFER_ASPECT_RATIO
// - ReShade::AspectRatio, ReShade::PixelSize, ReShade::ScreenSize
// - ReShade::BackBuffer, ReShade::DepthBuffer samplers
// - ReShade::GetLinearizedDepth(texcoord) helper
// - PostProcessVS() - standard fullscreen triangle vertex shader

ReShadeUI.fxh - UI Widget Types

hlsl

#include "ReShadeUI.fxh"

// Version checking
#define RESHADE_VERSION(major,minor,build) (10000 * (major) + 100 * (minor) + (build))
#define SUPPORTED_VERSION(major,minor,build) (__RESHADE__ >= RESHADE_VERSION(major,minor,build))

// UI type macros (version-aware, work across ReShade 3.x/4.x/5.x)
// __UNIFORM_INPUT_FLOAT1, __UNIFORM_SLIDER_FLOAT1, __UNIFORM_DRAG_FLOAT1
// __UNIFORM_COMBO_INT1, __UNIFORM_RADIO_INT1, __UNIFORM_COLOR_FLOAT3
// __UNIFORM_LIST_INT1 (ReShade 4.3+)

// Example usage:
uniform float MyValue < __UNIFORM_SLIDER_FLOAT1
    ui_min = 0.0; ui_max = 1.0;
    ui_label = "My Value";
> = 0.5;

uniform int MyChoice < __UNIFORM_COMBO_INT1
    ui_items = "Option A\0Option B\0Option C\0";
    ui_label = "Choice";
> = 0;

Depth Buffer Handling

Depth Configuration Defines

hlsl

// These can be set in ReShade preprocessor settings or defined before including ReShade.fxh
#ifndef RESHADE_DEPTH_INPUT_IS_UPSIDE_DOWN
    #define RESHADE_DEPTH_INPUT_IS_UPSIDE_DOWN 0
#endif
#ifndef RESHADE_DEPTH_INPUT_IS_REVERSED
    #define RESHADE_DEPTH_INPUT_IS_REVERSED 1    // 1 = reversed depth (1=near, 0=far)
#endif
#ifndef RESHADE_DEPTH_INPUT_IS_LOGARITHMIC
    #define RESHADE_DEPTH_INPUT_IS_LOGARITHMIC 0
#endif
#ifndef RESHADE_DEPTH_MULTIPLIER
    #define RESHADE_DEPTH_MULTIPLIER 1
#endif
#ifndef RESHADE_DEPTH_LINEARIZATION_FAR_PLANE
    #define RESHADE_DEPTH_LINEARIZATION_FAR_PLANE 1000.0
#endif

// Coordinate adjustments
#ifndef RESHADE_DEPTH_INPUT_Y_SCALE
    #define RESHADE_DEPTH_INPUT_Y_SCALE 1
#endif
#ifndef RESHADE_DEPTH_INPUT_X_SCALE
    #define RESHADE_DEPTH_INPUT_X_SCALE 1
#endif

Manual Depth Linearization

hlsl

float GetLinearizedDepth(float2 texcoord) {
#if RESHADE_DEPTH_INPUT_IS_UPSIDE_DOWN
    texcoord.y = 1.0 - texcoord.y;
#endif
#if RESHADE_DEPTH_INPUT_IS_MIRRORED
    texcoord.x = 1.0 - texcoord.x;
#endif
    texcoord.x /= RESHADE_DEPTH_INPUT_X_SCALE;
    texcoord.y /= RESHADE_DEPTH_INPUT_Y_SCALE;
    
    float depth = tex2Dlod(ReShade::DepthBuffer, float4(texcoord, 0, 0)).x * RESHADE_DEPTH_MULTIPLIER;
    
#if RESHADE_DEPTH_INPUT_IS_LOGARITHMIC
    const float C = 0.01;
    depth = (exp(depth * log(C + 1.0)) - 1.0) / C;
#endif
#if RESHADE_DEPTH_INPUT_IS_REVERSED
    depth = 1.0 - depth;
#endif
    
    const float N = 1.0;
    depth /= RESHADE_DEPTH_LINEARIZATION_FAR_PLANE - depth * (RESHADE_DEPTH_LINEARIZATION_FAR_PLANE - N);
    
    return depth;
}

// ReShade.fxh provides: ReShade::GetLinearizedDepth(texcoord)

Complete ReShade FX Template

hlsl

#include "ReShade.fxh"

uniform float Intensity <
    ui_type = "slider";
    ui_min = 0.0; ui_max = 1.0;
    ui_label = "Effect Intensity";
    ui_tooltip = "Controls the strength of the effect";
> = 0.5;

texture2D texTemp { Width = BUFFER_WIDTH; Height = BUFFER_HEIGHT; Format = RGBA8; };
sampler2D samplerTemp { Texture = texTemp; };

float3 PS_Main(float4 vpos : SV_Position, float2 texcoord : TEXCOORD) : SV_Target {
    float3 original = tex2D(ReShade::BackBuffer, texcoord).rgb;
    float3 processed = original * Intensity;
    return processed;
}

technique MyEffect <
    ui_label = "My Effect";
    ui_tooltip = "A simple effect template";
>
{
    pass
    {
        VertexShader = PostProcessVS;
        PixelShader = PS_Main;
    }
}

Common Post-Processing Techniques

Blending Modes

hlsl

namespace Blending {
    // Darken
    float3 Darken(float3 a, float3 b) { return min(a, b); }
    float3 Multiply(float3 a, float3 b) { return a * b; }
    float3 ColorBurn(float3 a, float3 b) {
        return (b.r > 0 && b.g > 0 && b.b > 0) ? 1.0 - min(1.0, (0.5 - a) / b) : 0.0;
    }
    float3 LinearBurn(float3 a, float3 b) { return max(a + b - 1.0, 0.0); }
    
    // Lighten
    float3 Lighten(float3 a, float3 b) { return max(a, b); }
    float3 Screen(float3 a, float3 b) { return 1.0 - (1.0 - a) * (1.0 - b); }
    float3 ColorDodge(float3 a, float3 b) {
        return (b.r < 1 && b.g < 1 && b.b < 1) ? min(1.0, a / (1.0 - b)) : 1.0;
    }
    float3 LinearDodge(float3 a, float3 b) { return min(a + b, 1.0); }
    
    // Contrast
    float3 Overlay(float3 a, float3 b) {
        return lerp(2 * a * b, 1.0 - 2 * (1.0 - a) * (1.0 - b), step(0.5, a));
    }
    float3 SoftLight(float3 a, float3 b) {
        return clamp(a - (1.0 - 2 * b) * a * (1 - a), 0, 1);
    }
    float3 HardLight(float3 a, float3 b) {
        return lerp(2 * a * b, 1.0 - 2 * (1.0 - b) * (1.0 - a), step(0.5, b));
    }
    
    // Inversion
    float3 Difference(float3 a, float3 b) { return max(a - b, b - a); }
    float3 Exclusion(float3 a, float3 b) { return a + b - 2 * a * b; }
}

---

Unity ShaderLab Reference

Unity uses ShaderLab, a declarative language that wraps HLSL/Cg code with additional Unity-specific features. File extension: .shader

Shader Structure

hlsl

Shader "Category/ShaderName"
{
    Properties
    {
        // Exposed properties visible in Inspector
    }
    
    SubShader
    {
        // GPU-specific rendering setup
        Pass
        {
            // Rendering pass
        }
    }
    
    FallBack "Diffuse"  // Optional fallback shader
}

Properties Block

hlsl

Properties
{
    // Basic types
    _Color ("Main Color", Color) = (1, 1, 1, 1)
    _MainTex ("Albedo (RGB)", 2D) = "white" {}
    _NormalMap ("Normal Map", 2D) = "bump" {}
    _Cutoff ("Alpha Cutoff", Range(0, 1)) = 0.5
    _Glossiness ("Smoothness", Range(0, 1)) = 0.5
    _Metallic ("Metallic", Range(0, 1)) = 0.0
    _EmissionColor ("Emission Color", Color) = (0, 0, 0, 1)
    
    // Advanced types
    _IntValue ("Integer", Int) = 1
    _FloatValue ("Float", Float) = 1.0
    _VectorValue ("Vector", Vector) = (1, 1, 1, 1)
    _CubeMap ("Environment Map", Cube) = "" {}
    _3DTex ("3D Texture", 3D) = "" {}
}

Type	Syntax	Description
Color	Color = (r, g, b, a)	Color picker in Inspector
2D	2D = "white" {}	2D texture (white, black, gray, bump)
3D	3D = "" {}	3D texture
Cube	Cube = "" {}	Cubemap texture
Range	Range(min, max) = default	Slider with min/max
Float	Float = default	Float input field
Int	Int = default	Integer input field
Vector	Vector = (x, y, z, w)	4-component vector field

SubShader Block

hlsl

SubShader
{
    // Render state setup
    Tags { "RenderType" = "Opaque" "Queue" = "Geometry" }
    LOD 200
    
    // Optional: Cull, ZWrite, ZTest, Blend, etc.
    Cull Back
    ZWrite On
    ZTest LEqual
    Blend SrcAlpha OneMinusSrcAlpha
    
    Pass
    {
        Name "BASE"  // Optional pass name
        Tags { "LightMode" = "ForwardBase" }
        
        // Per-pass state overrides
        Blend One One  // Additive blending for this pass
        
        CGPROGRAM
        // HLSL code here
        ENDCG
    }
}

SubShader Tags

Tag	Values	Description
RenderType	Opaque, Transparent, TransparentCutout, Background, Overlay	Shader replacement category
Queue	Background, Geometry, AlphaTest, Transparent, Overlay (+offset)	Render order
IgnoreProjector	True, False	Skip projector rendering
ForceNoShadowCasting	True, False	Disable shadow casting
PreviewType	Plane, Sphere, Skybox	Material preview shape

hlsl

Tags {
    "RenderType" = "Transparent"
    "Queue" = "Transparent+100"  // After standard transparent
    "IgnoreProjector" = "True"
    "ForceNoShadowCasting" = "True"
}

Render State Commands

hlsl

// Culling
Cull Back    // Default - cull back faces
Cull Front   // Cull front faces
Cull Off     // No culling (double-sided)

// Depth
ZWrite On    // Write to depth buffer
ZWrite Off   // Don't write to depth
ZTest LEqual // Default - pass if depth <= buffer
ZTest Greater
ZTest Less
ZTest Equal
ZTest Always

// Blending
Blend Off                                    // No blending
Blend SrcAlpha OneMinusSrcAlpha              // Standard alpha
Blend One One                                // Additive
Blend One OneMinusSrcAlpha                   // Premultiplied alpha
Blend DstColor Zero                          // Multiply
Blend SrcAlpha One                           // Soft additive
BlendOp Add                                  // Default blend operation

// Stencil
Stencil {
    Ref 1
    Comp Always
    Pass Replace
    Fail Keep
    ZFail Keep
}

Pass Tags (LightMode)

LightMode	Description
Always	Always rendered, regardless of lighting
ForwardBase	Main forward pass (main directional light, ambient, lightmaps)
ForwardAdd	Additional per-pixel lights (one pass per light)
Deferred	Deferred shading G-buffer pass
ShadowCaster	Shadow mapping pass
Meta	Lightmap baking pass
MotionVectors	Motion vector pass

Unity Shader Types

1. Unlit Shader

hlsl

Shader "Custom/UnlitExample"
{
    Properties
    {
        _MainTex ("Texture", 2D) = "white" {}
        _Color ("Color", Color) = (1, 1, 1, 1)
    }
    
    SubShader
    {
        Tags { "RenderType" = "Opaque" }
        
        Pass
        {
            CGPROGRAM
            #pragma vertex vert
            #pragma fragment frag
            
            #include "UnityCG.cginc"
            
            struct appdata
            {
                float4 vertex : POSITION;
                float2 uv : TEXCOORD0;
            };
            
            struct v2f
            {
                float2 uv : TEXCOORD0;
                float4 vertex : SV_POSITION;
            };
            
            sampler2D _MainTex;
            float4 _MainTex_ST;
            float4 _Color;
            
            v2f vert(appdata v)
            {
                v2f o;
                o.vertex = UnityObjectToClipPos(v.vertex);
                o.uv = TRANSFORM_TEX(v.uv, _MainTex);
                return o;
            }
            
            fixed4 frag(v2f i) : SV_Target
            {
                return tex2D(_MainTex, i.uv) * _Color;
            }
            ENDCG
        }
    }
}

2. Surface Shader

hlsl

Shader "Custom/SurfaceExample"
{
    Properties
    {
        _Color ("Color", Color) = (1, 1, 1, 1)
        _MainTex ("Albedo (RGB)", 2D) = "white" {}
        _Glossiness ("Smoothness", Range(0, 1)) = 0.5
        _Metallic ("Metallic", Range(0, 1)) = 0.0
        _Emission ("Emission", Color) = (0, 0, 0, 1)
    }
    
    SubShader
    {
        Tags { "RenderType" = "Opaque" }
        LOD 200
        
        CGPROGRAM
        #pragma surface surf Standard fullforwardshadows
        #pragma target 3.0
        
        sampler2D _MainTex;
        
        struct Input
        {
            float2 uv_MainTex;
            float3 worldPos;      // Built-in: world position
            float3 viewDir;       // Built-in: view direction
            float3 worldNormal;   // Built-in: world normal
        };
        
        half _Glossiness;
        half _Metallic;
        fixed4 _Color;
        fixed4 _Emission;
        
        void surf(Input IN, inout SurfaceOutputStandard o)
        {
            fixed4 c = tex2D(_MainTex, IN.uv_MainTex) * _Color;
            o.Albedo = c.rgb;
            o.Metallic = _Metallic;
            o.Smoothness = _Glossiness;
            o.Alpha = c.a;
            o.Emission = _Emission.rgb;
        }
        ENDCG
    }
    FallBack "Diffuse"
}

Surface Output Structures

hlsl

// Standard (PBR)
struct SurfaceOutputStandard
{
    fixed3 Albedo;      // Base color
    fixed3 Normal;      // Tangent space normal
    half3 Emission;     // Emissive color
    half Metallic;      // 0 = dielectric, 1 = metal
    half Smoothness;    // 0 = rough, 1 = smooth
    half Occlusion;     // Ambient occlusion
    fixed Alpha;        // Alpha for transparency
};

// Lambert
struct SurfaceOutput
{
    fixed3 Albedo;
    fixed3 Normal;
    fixed3 Emission;
    half Specular;
    fixed Gloss;
    fixed Alpha;
};

Surface Shader Directives

hlsl

// Lighting models
#pragma surface surf Lambert     // Diffuse
#pragma surface surf BlinnPhong  // Specular
#pragma surface surf Standard    // PBR metallic
#pragma surface surf StandardSpecular  // PBR specular

// Optional parameters
#pragma surface surf Lambert alpha        // Alpha blending
#pragma surface surf Lambert vertex:vert // Custom vertex function
#pragma surface surf Lambert finalcolor:mycolor // Final color modifier
#pragma surface surf Lambert addshadow   // Generate shadow caster pass
#pragma surface surf Lambert fullforwardshadows // Support all light types
#pragma surface surf Lambert noambient   // No ambient light
#pragma surface surf Lambert novertexlights // No per-vertex lights
#pragma surface surf Lambert nolightmap  // No lightmaps

// Shader model targets
#pragma target 2.5   // Default
#pragma target 3.0   // Required for some features
#pragma target 4.5   // DX11 shader model 4.5
#pragma target 5.0   // DX11 shader model 5.0

Built-in Include Files

hlsl

#include "UnityCG.cginc"        // Common functions and macros
#include "UnityStandardCore.cginc"  // Standard shader core
#include "Lighting.cginc"       // Lighting functions
#include "AutoLight.cginc"      // Automatic lighting macros
#include "HLSLSupport.cginc"    // Platform compatibility
#include "UnityShaderVariables.cginc" // Built-in variables

Unity Built-in Variables

Transform Matrices

hlsl

float4x4 UNITY_MATRIX_MVP;      // Model * View * Projection
float4x4 UNITY_MATRIX_MV;       // Model * View
float4x4 UNITY_MATRIX_V;        // View matrix
float4x4 UNITY_MATRIX_P;        // Projection matrix
float4x4 UNITY_MATRIX_VP;       // View * Projection
float4x4 unity_ObjectToWorld;   // Model matrix (local to world)
float4x4 unity_WorldToObject;   // Inverse model matrix

Camera & Screen

hlsl

float3 _WorldSpaceCameraPos;    // Camera position in world space
float4 _ProjectionParams;       // x = 1/-1 (normal/inverted), y = near, z = far, w = 1/far
float4 _ScreenParams;           // x = width, y = height, z = 1 + 1/width, w = 1 + 1/height

Time

hlsl

float4 _Time;       // (t/20, t, t*2, t*3) - game time
float4 _SinTime;    // (sin(t/8), sin(t/4), sin(t/2), sin(t))
float4 _CosTime;    // (cos(t/8), cos(t/4), cos(t/2), cos(t))
float4 unity_DeltaTime; // (dt, 1/dt, smooth dt, 1/smooth dt)

Lighting

hlsl

float4 _WorldSpaceLightPos0;    // Directional: (dir, 0), Point/Spot: (pos, 1)
float4 _LightColor0;            // RGB = color, A = intensity
float4 unity_AmbientSky;        // Sky ambient color
float4 unity_FogColor;          // Fog color
float4 unity_FogParams;         // Fog parameters

Unity Built-in Functions

hlsl

// Transform functions (UnityCG.cginc)
float3 UnityObjectToWorldNormal(float3 norm);    // Local normal to world
float3 UnityObjectToWorldDir(float3 dir);        // Local direction to world
float4 UnityObjectToClipPos(float3 pos);         // Local to clip space
float3 UnityViewToWorldDir(float3 dir);          // View to world direction

// Depth functions
float LinearEyeDepth(float rawDepth);            // Raw depth to eye depth
float Linear01Depth(float rawDepth);             // Raw depth to 0-1 linear

// UV functions
float2 TRANSFORM_TEX(float2 uv, sampler2D tex);  // Apply texture scale/offset

// Utility
float3 UnpackNormal(float4 packedNormal);        // Unpack normal map
float3 UnpackNormalWithScale(float4 packed, float scale); // With scale

GrabPass

hlsl

GrabPass
{
    "_BackgroundTexture"  // Store in named texture
}

// Later in another pass
sampler2D _BackgroundTexture;

fixed4 frag(v2f i) : SV_Target
{
    float2 uv = i.grabPos.xy / i.grabPos.w;
    fixed4 col = tex2D(_BackgroundTexture, uv);
    return col;
}

Multi-Compile & Shader Variants

hlsl

// Single keyword (on/off)
#pragma multi_compile FOG_ON FOG_OFF

// Built-in multi-compiles
#pragma multi_compile_fog           // Fog variants
#pragma multi_compile_instancing    // GPU instancing variants
#pragma multi_compile_fwdbase       // Forward base pass variants
#pragma multi_compile_fwdadd        // Forward add pass variants

// Usage in code
#ifdef FOG_ON
    color = lerp(color, unity_FogColor, fogFactor);
#endif

GPU Instancing

hlsl

Properties
{
    _Color ("Color", Color) = (1, 1, 1, 1)
}

SubShader
{
    Pass
    {
        CGPROGRAM
        #pragma vertex vert
        #pragma fragment frag
        #pragma multi_compile_instancing
        
        #include "UnityCG.cginc"
        
        struct appdata
        {
            float4 vertex : POSITION;
            UNITY_VERTEX_INPUT_INSTANCE_ID  // Required for instancing
        };
        
        UNITY_INSTANCING_BUFFER_START(Props)
            UNITY_DEFINE_INSTANCED_PROP(float4, _Color)
        UNITY_INSTANCING_BUFFER_END(Props)
        
        v2f vert(appdata v)
        {
            v2f o;
            UNITY_SETUP_INSTANCE_ID(v);
            UNITY_TRANSFER_INSTANCE_ID(v, o);
            o.vertex = UnityObjectToClipPos(v.vertex);
            return o;
        }
        
        fixed4 frag(v2f i) : SV_Target
        {
            UNITY_SETUP_INSTANCE_ID(i);
            return UNITY_ACCESS_INSTANCED_PROP(Props, _Color);
        }
        ENDCG
    }
}

Unity Shader Best Practices

1. Naming Convention: Use Category/Name format (e.g., "Custom/Water")
2. Organize shaders in dedicated folders (e.g., Assets/Shaders/)
3. Use LOD values for level-of-detail fallback
4. Test in different lighting conditions (forward, deferred, vertex-lit)
5. Consider mobile compatibility - use #pragma target 2.5 when possible
6. Use FallBack for older GPU support
7. Profile shader performance with Unity Frame Debugger
8. Batch similar materials using GPU instancing
9. Avoid discard/clip in mobile shaders (causes early-Z issues)
10. Use texture atlases to reduce draw calls

---

WebGL Reference

WebGL (Web Graphics Library) is a JavaScript API for hardware-accelerated 2D and 3D graphics in web browsers, based on OpenGL ES.

Context Initialization

javascript

// WebGL 1.0
const canvas = document.querySelector("canvas");
const gl = canvas.getContext("webgl") || canvas.getContext("experimental-webgl");

// WebGL 2.0 (preferred)
const gl = canvas.getContext("webgl2");

if (!gl) {
    console.error("WebGL not supported");
}

// Context creation options
const gl = canvas.getContext("webgl2", {
    alpha: false,              // No alpha channel (better performance)
    antialias: true,           // Antialiasing
    depth: true,               // Depth buffer
    stencil: false,            // Stencil buffer
    premultipliedAlpha: true,  // Alpha premultiplication
    preserveDrawingBuffer: false, // Keep buffer after render
    powerPreference: "high-performance", // GPU preference
});

WebGL Version Comparison

Feature	WebGL 1.0	WebGL 2.0
GLSL Version	GLSL ES 1.00	GLSL ES 3.00
Vertex Array Objects	Extension	Core
Instanced Rendering	Extension	Core
3D Textures	❌	✅
Sampler Objects	❌	✅
Uniform Buffer Objects	❌	✅
Multiple Render Targets	Extension	Core

Shader Compilation Pipeline

javascript

function createShader(gl, type, source) {
    const shader = gl.createShader(type);
    gl.shaderSource(shader, source);
    gl.compileShader(shader);
    
    if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
        console.error("Shader compilation error:", gl.getShaderInfoLog(shader));
        gl.deleteShader(shader);
        return null;
    }
    return shader;
}

function createProgram(gl, vertexShader, fragmentShader) {
    const program = gl.createProgram();
    gl.attachShader(program, vertexShader);
    gl.attachShader(program, fragmentShader);
    gl.linkProgram(program);
    
    if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
        console.error("Program linking error:", gl.getProgramInfoLog(program));
        gl.deleteProgram(program);
        return null;
    }
    return program;
}

// Usage
const vertexShader = createShader(gl, gl.VERTEX_SHADER, vsSource);
const fragmentShader = createShader(gl, gl.FRAGMENT_SHADER, fsSource);
const program = createProgram(gl, vertexShader, fragmentShader);

WebGL GLSL Shaders

Basic Vertex Shader (GLSL ES 1.00)

glsl

attribute vec3 aPosition;
attribute vec2 aTexCoord;
attribute vec3 aNormal;

uniform mat4 uModelMatrix;
uniform mat4 uViewMatrix;
uniform mat4 uProjectionMatrix;

varying vec3 vNormal;
varying vec2 vTexCoord;

void main() {
    vec4 worldPosition = uModelMatrix * vec4(aPosition, 1.0);
    gl_Position = uProjectionMatrix * uViewMatrix * worldPosition;
    vNormal = mat3(uModelMatrix) * aNormal;
    vTexCoord = aTexCoord;
}

Basic Fragment Shader (GLSL ES 1.00)

glsl

precision mediump float;

varying vec3 vNormal;
varying vec2 vTexCoord;

uniform sampler2D uTexture;
uniform vec3 uLightPosition;
uniform vec3 uLightColor;

void main() {
    vec3 normal = normalize(vNormal);
    vec3 lightDir = normalize(uLightPosition);
    float diff = max(dot(normal, lightDir), 0.0);
    
    vec4 texColor = texture2D(uTexture, vTexCoord);
    vec3 result = diff * uLightColor * texColor.rgb;
    
    gl_FragColor = vec4(result, texColor.a);
}

WebGL 2.0 Fragment Shader (GLSL ES 3.00)

glsl

#version 300 es
precision highp float;

in vec3 vNormal;
in vec2 vTexCoord;

uniform sampler2D uTexture;
uniform vec3 uLightColor;

out vec4 fragColor;

void main() {
    vec3 normal = normalize(vNormal);
    float diff = max(dot(normal, vec3(0.0, 1.0, 0.0)), 0.0);
    vec4 texColor = texture(uTexture, vTexCoord);
    fragColor = vec4(diff * uLightColor * texColor.rgb, texColor.a);
}

Buffer Management

javascript

// Create and populate a vertex buffer
const positionBuffer = gl.createBuffer();
gl.bindBuffer(gl.ARRAY_BUFFER, positionBuffer);

const positions = new Float32Array([
    -1.0, -1.0, 0.0,  // Vertex 1
     1.0, -1.0, 0.0,  // Vertex 2
     0.0,  1.0, 0.0   // Vertex 3
]);
gl.bufferData(gl.ARRAY_BUFFER, positions, gl.STATIC_DRAW);

// Buffer usage hints
// gl.STATIC_DRAW  - Data doesn't change
// gl.DYNAMIC_DRAW - Data changes occasionally
// gl.STREAM_DRAW  - Data changes every frame

Vertex Attributes

javascript

const positionLocation = gl.getAttribLocation(program, "aPosition");
gl.enableVertexAttribArray(positionLocation);
gl.vertexAttribPointer(
    positionLocation,  // Attribute location
    3,                 // Components per vertex (x, y, z)
    gl.FLOAT,          // Data type
    false,             // Normalize?
    0,                 // Stride (0 = tightly packed)
    0                  // Offset
);

Texture Handling

javascript

function createTexture(gl, image) {
    const texture = gl.createTexture();
    gl.bindTexture(gl.TEXTURE_2D, texture);
    gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, image);
    
    // Power-of-2 check
    if (isPowerOf2(image.width) && isPowerOf2(image.height)) {
        gl.generateMipmap(gl.TEXTURE_2D);
    } else {
        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
    }
    return texture;
}

// Texture filtering options
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR_MIPMAP_LINEAR);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);

Rendering Loop

javascript

function render(time) {
    gl.viewport(0, 0, canvas.width, canvas.height);
    gl.clearColor(0.0, 0.0, 0.0, 1.0);
    gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT);
    
    gl.enable(gl.DEPTH_TEST);
    gl.depthFunc(gl.LEQUAL);
    
    gl.useProgram(program);
    // Set uniforms and bind textures...
    gl.drawArrays(gl.TRIANGLES, 0, vertexCount);
    
    requestAnimationFrame(render);
}

Vertex Array Objects (VAO) - WebGL 2

javascript

// Create VAO
const vao = gl.createVertexArray();
gl.bindVertexArray(vao);

// Set up all vertex attributes
gl.bindBuffer(gl.ARRAY_BUFFER, positionBuffer);
gl.enableVertexAttribArray(positionLocation);
gl.vertexAttribPointer(positionLocation, 3, gl.FLOAT, false, 0, 0);

gl.bindVertexArray(null);

// In render loop
gl.bindVertexArray(vao);
gl.drawArrays(gl.TRIANGLES, 0, vertexCount);

Framebuffer Rendering (Render to Texture)

javascript

// Create framebuffer
const framebuffer = gl.createFramebuffer();
gl.bindFramebuffer(gl.FRAMEBUFFER, framebuffer);

// Create target texture
const targetTexture = gl.createTexture();
gl.bindTexture(gl.TEXTURE_2D, targetTexture);
gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, width, height, 0, gl.RGBA, gl.UNSIGNED_BYTE, null);

// Attach texture to framebuffer
gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, targetTexture, 0);

// Create depth renderbuffer
const depthBuffer = gl.createRenderbuffer();
gl.bindRenderbuffer(gl.RENDERBUFFER, depthBuffer);
gl.renderbufferStorage(gl.RENDERBUFFER, gl.DEPTH_COMPONENT16, width, height);
gl.framebufferRenderbuffer(gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, gl.RENDERBUFFER, depthBuffer);

// Check framebuffer status
if (gl.checkFramebufferStatus(gl.FRAMEBUFFER) !== gl.FRAMEBUFFER_COMPLETE) {
    console.error("Framebuffer incomplete");
}

// Render to framebuffer
gl.bindFramebuffer(gl.FRAMEBUFFER, framebuffer);
gl.viewport(0, 0, width, height);
// ... render scene ...

// Render to canvas
gl.bindFramebuffer(gl.FRAMEBUFFER, null);
gl.viewport(0, 0, canvas.width, canvas.height);
// ... use targetTexture ...

Blend Functions

javascript

// Standard alpha blending
gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);

// Additive blending
gl.blendFunc(gl.SRC_ALPHA, gl.ONE);

// Premultiplied alpha
gl.blendFunc(gl.ONE, gl.ONE_MINUS_SRC_ALPHA);

// Multiply
gl.blendFunc(gl.DST_COLOR, gl.ZERO);

WebGL Extensions

javascript

// Check for extension
const ext = gl.getExtension("OES_vertex_array_object");
if (ext) {
    const vao = ext.createVertexArrayOES();
}

// Common WebGL 1 extensions
gl.getExtension("ANGLE_instanced_arrays");        // Instanced rendering
gl.getExtension("OES_vertex_array_object");       // VAO support
gl.getExtension("OES_texture_float");             // Float textures
gl.getExtension("WEBGL_depth_texture");           // Depth textures
gl.getExtension("EXT_texture_filter_anisotropic"); // Anisotropic filtering

Performance Targets

Target	Frame Time	Draw Calls (Desktop)	Draw Calls (Mobile)
60 FPS	16.67ms	~1000-5000	~100-500
30 FPS	33.33ms	~2000-10000	~200-1000

Popular WebGL Libraries

Library	Description
three.js	Comprehensive 3D library with scene graph
Babylon.js	Game engine with physics and VR support
Pixi.js	Fast 2D WebGL renderer
regl	Functional WebGL wrapper
twgl	Tiny WebGL helper library
glMatrix	High-performance matrix/vector library

---

Performance Guidelines Summary

Critical Optimizations

1. Minimize texture samples - Cache results, use atlases, batch similar operations
2. Avoid dynamic branches - Use step(), mix(), min()/max() instead of if/else
3. Use appropriate precision - half/mediump for colors, float/highp for positions
4. Group uniforms in buffers - Reduce binding changes, align to 16-byte boundaries
5. Precompute in vertex shader - Pass varyings to fragment when possible
6. Avoid discard/kill - Causes early-Z optimization failures on some GPUs
7. Reduce overdraw - Render front-to-back with depth testing
8. Use mipmaps - Improves texture cache hit rate for distant objects

Transcendental Priority

Optimization	Impact	Effort	Validation
sin/cos → sincos	High	Low	✅ Always safe
pow(x, 2.0) → x * x	High	Low	✅ Always safe
pow(x, 3.0) → x * x * x	High	Low	✅ Always safe
Hoist repeated calls	Medium-High	Medium	✅ Always safe
sqrt(x) vs pow(x, 0.5)	Medium	Low	✅ Always safe (x ≥ 0)
Taylor approximations	Varies	Medium	⚠️ Test required