SPECTRE/SHACHI_INTERFACE_SPECS.md (841 lines)

• Defines 8 SPECTRE interface specs for the Shachi SDK on KOS
• Spec 1: VMU Interface — Device enumeration (sh_vmu_addr_t, sh_vmu_at, sh_vmu_first, sh_vmu_count, sh_vmu_each), screen rendering (sh_vmu_clear, sh_vmu_blit, sh_vmu_blit_xbm, sh_vmu_print, sh_vmu_printf, sh_vmu_present, sh_vmu_present_all, sh_vmu_set_font), save game management (sh_save_info_t, sh_save_result_t, sh_save_exists, sh_save_free_blocks, sh_save_write, sh_save_read, sh_save_delete, sh_save_load_icon). All sh_vmu_* screen functions are zero-cost wrappers around KOS vmufb.
• Spec 2: SH4 Math — Adopts DreamHAL sh4_math.h (public domain, Moopthehedgehog 2020). Types: sh_mat4_t (4x4 aligned), sh_vec4_t (4D aligned). Functions: sh_transform_points (batch FTRV), sh_perspective_divide, sh_normalize_batch, sh_vec4_lerp. Builds on KOS dc/fmath.h and dc/matrix.h.
• Spec 3: DC Native Asset Formats — Build-time pipeline: sh-texconv (PNG→PVR), sh-meshconv (OBJ→SHM). Texture formats: ARGB1555, RGB565, ARGB4444, YUV422, BUMP, PAL4, PAL8. Functions: sh_tex_load, sh_tex_load_kmg, sh_tex_free, sh_tex_load_vq, sh_mesh_load, sh_mesh_free. Custom .pvr format with sh_tex_header_t (magic ‘SHPT’, 16-byte) and .shm mesh format (sh_mesh_header_t, magic ‘SHFM’). VQ textures with 2048-byte codebook.
• Spec 4: Material System — Maps PVR2 polygon headers for multi-pass rendering. sh_material_pass_t (1:1 to pvr_poly_hdr_t), sh_material_t (1-4 passes). Predefined: opaque, transparent, punch-through, lightmapped, bumpmapped, envmapped. Compile step via sh_material_pass_compile/sh_material_compile_all.
• Spec 5: Compositor — Multi-view rendering with ordered views. sh_view_t (priority, viewport, camera matrices, submit callback), sh_compositor_t (max 8 views). sh_compositor_render wraps pvr_scene_begin/finish. VMU rendering is decoupled (Maple bus, not PVR2).
• Spec 6: Cooperative Task System — Lightweight coroutines via setjmp/longjmp (not KOS preemptive threads). sh_task_t, sh_scheduler_t (max 16 tasks, frame budget). Functions: sh_task_create, sh_task_yield, sh_task_sleep, sh_scheduler_tick. Async I/O via KOS worker thread underneath.
• Spec 7: Asset Manager — Generational-index asset pool (max 64 per type, fixed pools avoid malloc). sh_asset_id_t (index + generation + type), sh_asset_mgr_t. Functions: sh_assets_load_texture/mesh, sh_assets_get_texture/mesh, sh_assets_retain/release, sh_assets_valid, sh_assets_gc (scene transition), sh_assets_shutdown.
• Spec 8: Performance Profiler — Zone-based frame profiler wrapping KOS perfctr.h. sh_profiler_t (max 32 zones, 60-frame rolling average). Functions: sh_prof_init, sh_prof_frame_begin/end, sh_prof_zone_register/begin/end, SH_PROF_ZONE scoped macro, sh_prof_avg_frame_us, sh_prof_fps, sh_prof_print, sh_prof_dump, sh_prof_overlay. Zone overhead ~10ns. Stripped in NDEBUG builds.
• Implementation priority order: Spec 2 (P0) → Spec 8 (P0) → Spec 3 (P1) → Spec 4 (P1) → Spec 1 (P1) → Spec 7 (P2) → Spec 6 (P2) → Spec 5 (P3)