125 lines
4.6 KiB
Markdown
125 lines
4.6 KiB
Markdown
# 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).
|