b3dLoadEntityShader

Loads custom pixel shader for 3D entities (replaces default mesh shader with user-defined HLSL). Takes filename (HLSL source file path, .hlsl extension). Returns shader handle (positive integer, 0 on failure). Compiles HLSL pixel shader with entry point "PSMain" (Shader Model 5.0 ps_5_0 target), creates Pipeline State Object (PSO with custom pixel shader, default mesh vertex shader), stores in g_entityShaders map (indexed by shader ID, persistent until freed). Use for custom entity rendering (toon shading, cel shading, custom lighting), material effects (metallic, holographic, glowing), or special rendering (outline, silhouette, X-ray vision). Difference from screen shaders: entity shaders replace mesh pixel shader (per-entity rendering, different shader per mesh), screen shaders post-process final image (full-screen effect, applied after all rendering). Compilation: reads HLSL source file (text file read, must exist at path), compiles with D3DCompile (D3DCOMPILE_OPTIMIZATION_LEVEL3 flag, ps_5_0 target, entry point "PSMain"), captures compile errors (errorBlob contains error messages, displays line numbers and descriptions), creates bytecode (compiled shader binary, ready for PSO creation). PSO creation: uses default mesh vertex shader (g_meshVertexShaderBytecode, standard mesh VS), combines with custom pixel shader (user's HLSL, replaces default mesh PS), uses default mesh root signature (g_meshRootSignature, same resources as default meshes), input layout Vertex3D (7 elements: POSITION, NORMAL, TEXCOORD, COLOR, TANGENT, BLENDINDICES, BLENDWEIGHT), alpha blending enabled (SRC_ALPHA/INV_SRC_ALPHA, standard transparency), depth testing enabled (LESS comparison, depth writes on), backface culling (CULL_MODE_BACK, CCW front faces). Use cases: (1) Toon shader (shader = b3dLoadEntityShader("toon.hlsl") cel shading with discrete color bands), (2) Outline shader (shader = b3dLoadEntityShader("outline.hlsl") silhouette edge detection), (3) Holographic (shader = b3dLoadEntityShader("holo.hlsl") transparent scan lines), (4) Metallic (shader = b3dLoadEntityShader("metal.hlsl") environment reflection), (5) Custom lighting (shader = b3dLoadEntityShader("custom_light.hlsl") stylized lighting model). Common patterns: load = shader = b3dLoadEntityShader("effect.hlsl"), If shader = 0 Then Print "Failed"; apply = b3dEntityShader(entity, shader) assign to entity. Typical workflow: write HLSL shader (create .hlsl file with PSMain() pixel shader function), load shader (this function, returns handle), configure parameters (b3dSetEntityShaderFloat/Int/Float2/etc set uniforms), assign to entity (b3dEntityShader applies shader to specific mesh), render (b3dRenderWorld uses custom shader for that entity). HLSL shader requirements: entry point "PSMain" (function PSMain must exist, pixel shader entry), ps_5_0 target (Shader Model 5.0 pixel shader, DX12 compatible), input signature matches VS output (POSITION, NORMAL, TEXCOORD, COLOR, TANGENT, WORLDPOS semantics from vertex shader), output color (float4 return or SV_Target semantic, RGBA color), cbuffer compatibility (must match CustomShaderParams cbuffer layout, see ToonShader.hlsl example). Vertex shader output: POSITION (SV_Position, clip-space position), NORMAL (world-space normal vector), TEXCOORD (UV coordinates 0.0-1.0), COLOR (vertex color RGBA), TANGENT (tangent vector for normal mapping), WORLDPOS (world-space position for lighting), all available in pixel shader input. Root signature resources: cbuffer register(b0) (per-object transforms, world/view/projection matrices), cbuffer register(b1) (material properties, diffuse/specular/ambient colors, texture flags), cbuffer register(b2) (lighting data, light positions/colors/types), cbuffer register(b3) (CustomShaderParams, user parameters via b3dSetEntityShaderFloat/etc), textures t0-t7 (entity textures, diffuse/normal/specular/etc), sampler s0 (linear sampler for texture sampling). Performance: compilation slow (first load ~50-500ms depending on shader complexity, compile time varies), PSO creation ~1-5ms (GPU state object creation, one-time cost), recommend precompiled shaders for distribution (DXC offline compilation, instant loading, but not currently supported - only runtime compilation), shader caching (loaded shaders stored in g_entityShaders map, persistent until b3dFreeEntityShader called). Shader reflection: uses D3DReflect (inspects shader input signature, constant buffers, bound resources), DEBUG_COUT outputs (prints shader details during load, useful for debugging), validates VS/PS compatibility (checks vertex shader output matches pixel shader input, prevents signature mismatch errors). 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 with line numbers), 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 stderr (console output with error text, line numbers, syntax errors), file errors print stderr (file open/read failures, path not found), PSO errors print debug info (pipeline state creation failed, validation details). Related: b3dFreeEntityShader frees shader (releases GPU resources, removes from map), b3dEntityShader applies shader to entity (assigns shader handle to specific mesh), b3dGetEntityShader queries entity's shader (returns shader handle assigned to entity), b3dSetEntityShaderFloat sets shader parameter (float uniform variable), b3dSetEntityShaderInt sets shader parameter (integer uniform variable), b3dSetEntityShaderFloat2/Float3/Float4 set vector parameters (vec2/vec3/vec4 uniforms), b3dSetEntityShaderTexture sets shader texture (custom texture binding).