Debugging & Tooling

Always check GL_COMPILE_STATUS / GL_LINK_STATUS and print info logs; use glslangValidator to validate offline (catches errors that a lenient driver may accept).

36.1 Compilation errors

Always check GL_COMPILE_STATUS / GL_LINK_STATUS and print info logs; use glslangValidator to validate offline (catches errors that a lenient driver may accept). Different drivers (NVIDIA, AMD, Intel, mobile) differ in strictness — test on multiple vendors.

36.2 Common bugs

shader failed to compile/link, wrong uniform location, gl_Position.w = 0, back-face culling, depth test, NaNs everything white/oversaturated missing tone mapping, wrong light units, unnormalized vectors lighting "follows the camera" mixing coordinate spaces (view vs world) faceted or wrong normals forgot to normalize after interpolation, wrong normal matrix texture upside down image origin vs OpenGL texture origin washed-out or too dark colors sRGB/linear mistakes (gamma applied twice or not at all) shadow acne / peter-panning seams on mip boundaries / noisy edges derivatives in divergent control flow, wrong texture wrap mode flickering in the distance z-fighting (depth precision: increase near plane, reversed-Z with float depth) works on one GPU but not another undefined behavior: uninitialized variables, pow of negatives, division by zero, out-of-bounds array access, precision assumptions

36.3 Tools & techniques

RenderDoc: capture frames, inspect pipeline state, textures, buffers, mesh data, and step through shaders (debugging pixels/vertices).

NVIDIA Nsight Graphics, AMD RGP/RGA, PIX (DirectX), Spector.js (WebGL), browser WebGL Inspector.

Output debug colors and visualize intermediate values (normals, UVs, depth, NaN masks, heat maps of loop iterations).

GL_EXT_debug_printf in Vulkan (with validation layers) — printf from shaders.

OpenGL debug output (glDebugMessageCallback, GL_KHR_debug) and Vulkan validation layers.

Hot reloading of shader files to iterate quickly.