XCEngine/engine/include/XCEngine/Rendering/AGENTS.md

Rendering Agent Guide

This file records the long-term rendering direction and the architecture cuts already made. It is intentionally not a full map of the current implementation.

If this file conflicts with the current code, trust the code and update this file in the same change.

Long-Term Goal

The rendering module is moving toward a Unity SRP / URP style model:

• GraphicsSettings.renderPipelineAsset == null selects the built-in pipeline.
• GraphicsSettings.renderPipelineAsset != null selects the programmable SRP path.
• The managed product shape should stay close to: ScriptableRenderPipelineAsset -> ScriptableRendererData -> ScriptableRenderer -> ScriptableRendererFeature/ScriptableRenderPass.
• ScriptableRenderPipelineHost is the native host for managed SRP execution; it must not become a hidden fallback renderer when managed SRP planning or recording fails.
• Managed SRP / URP owns renderer selection, stage planning, feature/pass organization, camera policy, and optional stage requests such as shadow, depth, post-process, and final output.
• Native rendering owns scene extraction, renderer-list drawing, render graph execution, fullscreen primitive execution, and built-in private draw kernels.
• Public managed scene drawing should expose drawing capability, not native built-in injection order. Keep the public surface centered on DrawRenderers(...), DrawSkybox(), DrawOpaqueRenderers(), and DrawTransparentRenderers().
• Do not reintroduce implicit project-default SRP activation, hidden ScriptableRenderPipelineHost fallback, or public managed wrappers for built-in private scene injection points.
• Future URP alignment should add managed-side renderer/pass/render-graph capability. It should not reopen native private fallback paths just to make a feature appear to work.

Past Execution

• Established the top-level selection rule: explicit null means built-in, explicit managed asset means SRP, and runtime startup must not silently assign ProjectDefaultRenderPipelineAsset.
• Removed public managed native scene injection APIs such as ScriptableRenderContext.RecordSceneInjectionPoint(...), RecordBefore/After*Injection(...), and RecordOpaque/Skybox/TransparentScenePhase(...).
• Kept RecordScene() / RecordScenePhase(...) internal and made the public managed scene surface express draw operations through DrawRenderers(...), DrawSkybox(), DrawOpaqueRenderers(), and DrawTransparentRenderers().
• Moved renderer-backed SRP stage ownership into ScriptableRenderer, ScriptableRendererFeature, and ScriptableRenderPass; renderer-backed assets clear native optional stage defaults before managed renderer/features explicitly request the stages they need.
• Removed CameraRenderRequestContext.hasDirectionalShadow and ClearDirectionalShadow() from the ScriptCore public surface. Core keeps only internal bridge access, while URP policy belongs in renderer asset, renderer data, and feature code.
• Reordered managed camera request policy so managed / URP first observes the native directional-shadow baseline, then the final managed policy recomputes or clears the request without native planning adding it back afterward.
• Prevented URP default renderer feature factories from auto-injecting built-in private feature wrappers.
• Tightened SRP creation failure semantics: ManagedScriptableRenderPipelineAsset::CreatePipeline() fails when managed runtime, backend asset, or stage recorder is unavailable; factory fallback then returns the built-in pipeline instead of letting ScriptableRenderPipelineHost impersonate a successful managed SRP.