b3dLoadScreenShader

Loads custom screen shader from file (.hlsl runtime compile or .cso precompiled, full-screen post-processing effects). Takes filename (shader path, .hlsl source or .cso compiled bytecode). Returns shader handle (positive integer, 0 on failure). Loads HLSL source for runtime compilation (D3DCompile with Shader Model 5.0, ps_5_0 target, optimization level 3) or CSO precompiled bytecode (binary format from DXC or fxc compiler), creates pipeline state object (PSO with pixel shader, full-screen quad vertex shader), stores in g_screenShaders3D map (indexed by shader ID, persistent until freed). Use for custom post-processing effects (CRT scanlines, blur, vignette, color grading), visual filters (noir black-and-white, sepia tone, thermal vision), or special effects (distortion, chromatic aberration, film grain). File type detection: .hlsl extension = runtime compilation (source code compiled at load time, D3DCompile API, shows compile errors with line numbers), .cso extension or other = precompiled bytecode (binary blob loaded directly, faster load but no error messages, compiled offline with DXC/fxc). Runtime compilation: reads HLSL source file (std::ifstream text file read), compiles with D3DCompile (D3DCOMPILE_OPTIMIZATION_LEVEL3 flag, ps_5_0 target, entry point "main"), captures compile errors (errorBlob contains error messages, displays line numbers and descriptions via MessageBox), creates bytecode vector (compiled shader binary, ready for PSO creation). Precompiled loading: reads CSO binary file (std::ifstream binary read, seekg to get file size), loads entire file into bytecode vector (no compilation, just file->memory copy), faster load time (no compile step, instant loading), requires external compilation (DXC or fxc.exe used offline to create .cso from .hlsl). Pipeline state creation: uses full-screen quad vertex shader (g_quadVertexShaderSource3D, generates triangle strip covering screen), combines with loaded pixel shader (user's custom shader, post-processing effect), creates PSO (ID3D12PipelineState, root signature, render target format DXGI_FORMAT_R8G8B8A8_UNORM), stores PSO in ScreenShader3D structure (shader.pipelineState, ready for rendering). Use cases: (1) CRT effect (shader = b3dLoadScreenShader("crt.hlsl") scanlines and curvature), (2) Color grading (shader = b3dLoadScreenShader("lut.hlsl") cinematic color lookup table), (3) Blur filter (shader = b3dLoadScreenShader("gaussian.hlsl") Gaussian blur post-processing), (4) Distortion (shader = b3dLoadScreenShader("underwater.hlsl") underwater wave distortion), (5) Film grain (shader = b3dLoadScreenShader("noise.hlsl") film grain overlay). Common patterns: load = shader = b3dLoadScreenShader("effect.hlsl"), If shader = 0 Then Print "Failed"; apply = b3dApplyScreenShader(shader) use shader this frame. Typical workflow: write HLSL shader (create .hlsl file with main() pixel shader function), load shader (this function, returns handle), configure parameters (b3dSetShaderFloat/Int/Float2/etc set uniform variables), apply shader (b3dApplyScreenShader activates for frame), render (engine applies shader as full-screen post-processing). HLSL shader requirements: entry point "main" (function main() must exist, pixel shader entry), ps_5_0 target (Shader Model 5.0 pixel shader, DX12 compatible), full-screen quad input (SV_Position semantic, screen-space pixel coordinates), output color (float4 return or SV_Target semantic, RGBA color). Shader access: sceneTexture (main render target, input texture with scene content), samplerState (linear sampler, for texture sampling), constant buffer (optional, user parameters via b3dSetShaderFloat etc), typical signature: float4 main(float4 pos : SV_Position) : SV_Target. Performance: runtime compilation slow (first load ~50-500ms depending on shader complexity, compile time varies), precompiled fast (instant load <1ms, no compilation overhead), PSO creation ~1ms (GPU state object creation, one-time cost), recommend precompiled for distribution (ship .cso files, avoid runtime compile delays). Shader caching: loaded shaders stored in g_screenShaders3D map (persistent until b3dFreeScreenShader called), shader ID increments (g_nextShaderId3D, unique handle per shader), multiple shaders supported (load many effects, switch between them with b3dApplyScreenShader). Validation: returns 0 if filename null (null pointer error, invalid parameter), returns 0 if file not found (open failed, file doesn't exist at path), returns 0 if HLSL compile fails (syntax errors, invalid shader code, error message shown), returns 0 if CSO read fails (corrupted file, invalid binary format), returns 0 if PSO creation fails (GPU resource allocation failed, incompatible shader), check return value (If shader = 0 Then error, handle failure). Error reporting: HLSL compile errors show MessageBox (Windows dialog with error text, line numbers, syntax errors), stderr prints (console output for debugging, file and error details), CSO errors print to stderr (file open/read failures, no detailed errors), PSO errors print to stderr (pipeline state creation failed, generic GPU error). Related: b3dFreeScreenShader frees shader (releases GPU resources, removes from map), b3dApplyScreenShader applies shader (activates for frame, sets active shader), b3dClearScreenShader clears active shader (reverts to default rendering), b3dSetShaderFloat sets shader parameter (uniform variable, float value), b3dSetShaderFloat2/Float3/Float4 set vector parameters (multiple component uniforms).