# 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).