b2dLoadImageShader

Loads custom pixel shader for 2D images (.hlsl runtime compile or .cso precompiled, ps_5_0, global shader state). Takes filename (shader file path, string, .hlsl or .cso extension). Returns shader handle (positive integer, use with b2dDrawImageEx), returns 0 on failure (file not found, compilation error, PSO creation failed). Detects file type by extension (.hlsl = runtime compile with D3DCompile, .cso = load precompiled bytecode), compiles HLSL if needed (entry point "main", Shader Model ps_5_0, optimization level 3), creates pipeline state object (custom pixel shader + default 2D vertex shader), stores in g_2D_imageShaders map (indexed by handle, holds bytecode + PSO + parameter maps). Use for image effects (glow, outline, distortion), per-image post-processing (selective shader application), UI effects (button hover, selection highlight), or dynamic visuals (animated shaders, procedural patterns). Shader types supported: .hlsl source (runtime compilation, slower first load, easier development/iteration), .cso bytecode (precompiled with fxc.exe or dxc.exe, fast load, production-ready). HLSL requirements: entry point must be "main" (void main(PS_INPUT input) : SV_TARGET), Shader Model ps_5_0 (compatible with D3D12), pixel shader only (vertex shader provided by engine), outputs float4 color (return value or out parameter). Use cases: (1) Glow effect (shader=b2dLoadImageShader(\"glow.hlsl\"): b2dSetImageShaderFloat(shader,\"intensity\",2.0): b2dDrawImageEx(img,x,y,shader)), (2) Outline shader (outlineShader=b2dLoadImageShader(\"outline.cso\"): b2dSetImageShaderFloat4(outlineShader,\"color\",1,0,0,1): b2dDrawImageEx(selectedUnit,x,y,outlineShader)), (3) Distortion (waveShader=b2dLoadImageShader(\"wave.hlsl\"): b2dSetImageShaderFloat(waveShader,\"time\",elapsed): b2dDrawImageEx(water,x,y,waveShader)), (4) Global state (b2dSetImageShader(glowShader): draw multiple images all use shader: b2dSetImageShader(0) reset). Common patterns: load = shader=b2dLoadImageShader(\"effect.hlsl\") runtime compile; precompiled = shader=b2dLoadImageShader(\"effect.cso\") fast load. Runtime compilation: D3DCompile API (requires D3DCompiler DLL), entry "main" (fixed entry point name), ps_5_0 target (Shader Model 5.0 pixel shader), optimization level 3 (D3DCOMPILE_OPTIMIZATION_LEVEL3 for performance), prints errors (compilation failures output to console with filename + error message). Pipeline state: custom pixel shader (user-provided HLSL/bytecode), default vertex shader (engine quad renderer with transform cbuffer), blend state (alpha blending enabled SRC_ALPHA/INV_SRC_ALPHA), rasterizer (no culling, solid fill), creates PSO (stored in shader.pipelineState, used during rendering). Shader parameters: floatParams map (stores float uniforms set by b2dSetImageShaderFloat/2/3/4), intParams map (stores int uniforms set by b2dSetImageShaderInt), uploaded to GPU during rendering (parameters packed into constant buffer, available in shader). Per-draw shaders: b2dDrawImageEx shader parameter specifies shader for individual image draws, shader=0 (default rendering, no custom shader, uses standard alpha blend). Performance: .hlsl first load slow (D3DCompile ~10-100ms depending on shader complexity, PSO creation ~1-10ms), .cso load fast (binary read + PSO creation ~1-5ms, no compilation), runtime cost (shader executes per-pixel during draw, simple shaders ~0.01ms, complex ~0.1-1ms per image). Validation: returns 0 if file not found (no error message beyond console print), returns 0 if compilation fails (HLSL errors printed to console), returns 0 if PSO creation fails (D3D12 PSO creation error), handle valid until freed (use handle with Set/Free functions, stored in global map). Related: b2dFreeImageShader releases shader (deallocates resources, should not use handle after freeing), b2dSetImageShaderFloat/Int/etc set shader parameters (configure uniforms), b2dDrawImageEx draws with per-draw shader (specify shader for individual image draws).