Rendering Ownership

Public graphics contracts under pixelbullet/graphics are backend-neutral. They define renderer, render target/stage, frame submission, GPU selection and session data, materials, mesh payloads, and resource-cache concepts. engine/src/graphics implements neutral facades and factories.

The concrete renderer is Vulkan. Its focused packages under engine/backend/graphics/vulkan include:

engine/backend/graphics/vulkan/{core,devices,commands};
engine/backend/graphics/vulkan/{buffers,images,descriptors,pipelines};
engine/backend/graphics/vulkan/passes for classic render-pass and framebuffer construction;
engine/backend/graphics/vulkan/presentation for swapchain acquisition and presentation;
engine/backend/graphics/vulkan/runtime for frame flow and render-stage/runtime state;
engine/backend/graphics/vulkan/scene for scene resource resolution and subrender runtimes;
engine/backend/graphics/vulkan/diagnostics/gpu_listing;
engine/backend/graphics/vulkan/ui/imgui and engine/backend/graphics/vulkan/ui/rmlui.

Production framework, editor, tool, example, and product code uses neutral graphics or integration contracts. Vulkan handles and types stay behind backend factories and internal test-support surfaces.

Render Data And Asset Boundaries

Neutral render-facing mesh value types live in pixelbullet/graphics/mesh_types.h. Renderer-facing mesh payload loading uses pixelbullet/integration/graphics/meshes/mesh_data.h.

Neutral material values and their node serialization live in pixelbullet/graphics/material_types.h and pixelbullet/graphics/material_serialization.h. Vulkan material loading uses pixelbullet/integration/graphics/materials/material_data.h rather than the asset-owned Material file-IO class.

Environment, texture, and other renderer-facing payloads follow the same pattern: asset-owned schema and IO sit behind narrow graphics integration facades. Scene render extraction stays backend-neutral; Vulkan scene runtimes consume the extracted data.

Current Renderer Contract

The renderer is desktop-first and Vulkan 1.3-capable. It currently uses classic render passes/stages, runtime shader-source compilation for development and editor workflows, contiguous reflected descriptor sets beginning at set zero, and explicit VertexLayout contracts.

World and owned-view mesh pipelines share immutable pipeline bundles when their render-stage compatibility shape matches. Their uniforms, descriptors, resolved resources, and draw state remain independent. World and owned-view sprite pipelines use the same sharing rule.

Device-validated native pipeline cache data and source-validated SPIR-V cache data are best-effort per-binary settings. Missing, stale, invalid, or driver-incompatible cache data is ignored. Shader sources with includes bypass the SPIR-V cache because include dependency tracking is not part of the current contract.

Replaced descriptor sets retire after frame reuse. Other GPU resources retain their current conservative lifetimes. Initial swapchain creation does not wait for device idle; recreation may do so while existing work is drained.

Scene-Play Presentation Profiles

ScenePlayPresentationProfile selects the application-level renderer composition:

ShadowedMesh for mesh-only scene presentation;
ShadowedMeshWithSprites for the generic hybrid authored-scene path;
SpriteOnly for an intentional sprite-only composition.

The profile is composition policy, not authored scene data. The example classification explains why Sprite Gallery retains its executable source-level profile lesson.

ImGui

Application ImGui is an optional application feature, not a generic layer concept. Public headers live under engine/include/pixelbullet/application/imgui; neutral implementation is under engine/src/application/imgui; the GLFW adapter is under engine/src/application/imgui/glfw; Vulkan submission is under engine/backend/graphics/vulkan/ui/imgui.

Generic layers use UI-toolkit-neutral lifecycle names such as OnUiFrame. Editor code depends on focused ImGui headers and only links the implementation where it constructs or calls non-inline behavior.

RmlUi

Runtime UI values and documents are owned by framework/ui. The neutral engine integration contract is under engine/integration/ui/rmlui, lifecycle and source adaptation are under engine/src/ui/rmlui with includes rooted at pixelbullet/ui/rmlui, and Vulkan drawing is under engine/backend/graphics/vulkan/ui/rmlui.

framework/ui does not depend on scene play. Scene play projects gameplay state into UI-owned inputs, and editor authoring previews construct UI fixtures without manufacturing live gameplay state.

Deferred Work

Shader packaging, asynchronous compilation, dynamic rendering, broader deferred destruction, frame-graph work, and an RHI are not current invariants. Future renderer work is tracked in the graphics roadmap.