Publish Chimera GFX source

2026-09-03 03:27:14 +02:00
commit a6037502d7
828 changed files with 100454 additions and 0 deletions
@@ -0,0 +1,124 @@
+# Chimera GFX
+
+Chimera GFX is an experimental, open-source graphics abstraction for native
+PlayStation 5 homebrew. It provides a small C11 API, a deterministic host
+backend, and disabled-by-default platform adapters so graphics code can be
+designed and tested without a console.
+
+The project is useful today for:
+
+- developing and testing renderer-independent code on a normal workstation;
+- reviewing a capability-honest PS5 backend without enabling device actions;
+- integrating the API boundary with SDL2 or RetroArch scaffolding; and
+- reproducing the project's safety, provenance, and compatibility checks.
+
+It is research software, not a finished PS5 graphics driver. There is no GNM
+renderer, shader compiler, GPU allocator, deployment command, automatic
+startup, or supported device-execution workflow in this repository.
+
+## Current status
+
+| Area | Status |
+|---|---|
+| Public C API | Implemented and versioned |
+| Host mock backend | Implemented and covered by tests |
+| PS5 capability probe | Compile-only and fail-closed by default |
+| SDL2 / RetroArch adapters | Offline scaffolding; not a supported runtime |
+| Hardware-accelerated rendering | Not implemented |
+| Device deployment or execution | Intentionally absent |
+
+The default firmware identifier is `NONE`. A firmware allowlist permits an
+offline build only; it is not a compatibility claim or permission to transfer
+or execute an artifact. See [SAFETY.md](SAFETY.md) and
+[FIRMWARE_COMPATIBILITY.md](FIRMWARE_COMPATIBILITY.md).
+
+## Build and test on a workstation
+
+Requirements:
+
+- CMake 3.21 or newer;
+- Ninja;
+- a C11 compiler; and
+- Python 3.10 or newer.
+
+```sh
+cmake --preset host-debug
+cmake --build --preset host-debug
+ctest --preset host-debug
+```
+
+The host build is deterministic and does not communicate with a console.
+Windows users can run the equivalent helper:
+
+```powershell
+./tools/build-host.ps1
+```
+
+## Use the API
+
+Include the public header:
+
+```c
+#include <chimera/gfx/chimera_gfx.h>
+```
+
+The API models contexts, capabilities, surfaces, textures, uploads, presents,
+errors, and ordered cleanup. Application code should query capabilities,
+validate every result, and destroy child resources before their context.
+
+The mock backend is the supported starting point for application development.
+It performs host-memory state transitions only and produces no real graphics
+output. The public declarations and lifecycle rules live in
+[`include/chimera/gfx/chimera_gfx.h`](include/chimera/gfx/chimera_gfx.h); the
+tests are executable usage examples.
+
+## Optional PS5 compile check
+
+The locked public SDK reference and checksum are recorded in
+[`manifests/upstreams.lock.json`](manifests/upstreams.lock.json). After placing
+that SDK in an ignored local workspace, a compile-only probe can be configured:
+
+```sh
+cmake -S . -B build-ps5 \
+  -DCMAKE_TOOLCHAIN_FILE="$PS5_PAYLOAD_SDK/toolchain/prospero.cmake" \
+  -DCHIMERA_GFX_BUILD_PS5_PROBE=ON
+cmake --build build-ps5
+```
+
+Do not run the produced ELF. Building does not authorize transfer or execution,
+and the repository deliberately contains no deploy, upload, boot, or run target.
+
+## Repository map
+
+- `include/chimera/gfx/` — stable public API and adapter interfaces
+- `src/core/` — backend-independent validation and lifecycle logic
+- `src/backends/mock/` — deterministic host backend
+- `src/backends/ps5/` — fail-closed capability-probe implementation
+- `samples/` — disabled or host-reviewable examples
+- `adapters/` — SDL2 and RetroArch integration boundaries
+- `tests/` — host tests and policy checks
+- `manifests/` — upstream pins, provenance, and historical decisions
+- `docs/` — architecture decisions, research history, and safety evidence
+- `tools/` — reproducibility, validation, and audit helpers
+
+For design context, read [ARCHITECTURE.md](ARCHITECTURE.md). Contributors
+should start with [CONTRIBUTING.md](CONTRIBUTING.md), and security reports
+should follow [SECURITY.md](SECURITY.md).
+
+## Scope and safety
+
+Chimera GFX accepts only public, redistributable technical information. Do not
+contribute proprietary SDK material, leaked headers or binaries, exploit code,
+DRM bypasses, firmware dumps, credentials, private network data, or copyrighted
+game content.
+
+Historical manifests document why experimental paths are blocked. They are not
+instructions or active approvals. Every tracked execution authorization is
+consumed or false, and generated artifacts, device captures, SDK archives, and
+local operator records remain outside Git.
+
+## License
+
+Chimera GFX is licensed under
+[GPL-3.0-or-later](LICENSE). Third-party references and their license evidence
+are listed in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).