Loads custom pixel shader for 2D text rendering (.hlsl runtime compile or .cso precompiled, ps_5_0, global text shader state).
Takes filename (shader file path, string, .hlsl or .cso extension).
Returns shader handle (positive integer, use with b2dDrawTextEx), returns 0 on failure (file not found, compilation error, PSO creation failed).
Shaders
Parameters & Returns
Parameters
filenameString
Returns
Int
Quick Summary
Loads custom pixel shader for 2D text rendering (.hlsl runtime compile or .cso precompiled, ps_5_0, global text shader state).
Takes filename (shader file path, string, .hlsl or .cso extension).
Returns shader handle (positive integer, use with b2dDrawTextEx), returns 0 on failure (file not found, compilation error, PSO creation failed).
Technical Exegesis...
Loads custom pixel shader for 2D text rendering (.hlsl runtime compile or .cso precompiled, ps_5_0, global text shader state). Takes filename (shader file path, string, .hlsl or .cso extension). Returns shader handle (positive integer, use with b2dDrawTextEx), returns 0 on failure (file not found, compilation error, PSO creation failed). Detects file type by extension (.hlsl = runtime compile with D3DCompile, .
Loads custom pixel shader for 2D text rendering (.hlsl runtime compile or .cso precompiled, ps_5_0, global text shader state). Takes filename (shader file path, string, .hlsl or .cso extension). Returns shader handle (positive integer, use with b2dDrawTextEx), 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 text vertex shader), stores in g_2D_textShaders map (indexed by handle, holds bytecode + PSO + parameter maps). Use for text effects (outline, shadow, glow on text), text styling (gradient fills, patterns, custom colors), special rendering (rainbow text, animated text effects), or UI text (highlighted text, error/warning colors). 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) Text outline (shader=b2dLoadTextShader("text_outline.hlsl"): b2dSetTextShaderFloat4(shader,"outlineColor",1,1,0,1): b2dSetTextShader(shader): b2dText("Outlined",x,y)), (2) Text glow (glowShader=b2dLoadTextShader("text_glow.cso"): b2dSetTextShaderFloat(glowShader,"intensity",2.5): b2dSetTextShader(glowShader)), (3) Gradient text (gradShader=b2dLoadTextShader("gradient.hlsl"): b2dSetTextShaderFloat4(gradShader,"color1",1,0,0,1): b2dSetTextShaderFloat4(gradShader,"color2",0,0,1,1)), (4) Animated text (animShader=b2dLoadTextShader("wave.hlsl"): b2dSetTextShaderFloat(animShader,"time",elapsed)). Common patterns: load = shader=b2dLoadTextShader("effect.hlsl") runtime compile; precompiled = shader=b2dLoadTextShader("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 text quad renderer with glyph atlas UVs), blend state (alpha blending enabled SRC_ALPHA/INV_SRC_ALPHA), rasterizer (no culling, solid fill), creates PSO (stored in shader.pipelineState, used during text rendering). Shader parameters: floatParams map (stores float uniforms set by b2dSetTextShaderFloat/2/3/4), intParams map (stores int uniforms set by b2dSetTextShaderInt), uploaded to GPU during rendering (parameters packed into constant buffer, available in shader). Per-draw shaders: b2dDrawTextEx shader parameter specifies shader for individual text draws, shader=0 (default rendering, no custom shader, uses standard text rendering). 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 text draw, simple shaders ~0.01ms, complex ~0.1-1ms per text string). 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: b2dFreeTextShader releases shader (deallocates resources, should not use handle after freeing), b2dSetTextShaderFloat/Int/etc set shader parameters (configure uniforms), b2dDrawTextEx draws with per-draw shader (specify shader for individual text draws).