# Platform -- PlayStation Vita

`DUSK_TARGET_SYSTEM`: `vita`  
Source layer: `src/duskvita/`  
Renderer: vitaGL (OpenGL-over-GXM compatibility layer)

---

## Overview

The PlayStation Vita is an ARM-based handheld with 512 MB of RAM and a
960x544 OLED/LCD display. It uses SDL2 (ported to Vita) for input
abstraction, but the graphics layer is vitaGL -- an OpenGL compatibility
shim that translates OpenGL calls to Sony's native GXM API.

The distribution format is a `.vpk` (Vita Package) file containing the
signed executable and `dusk.dsk` bundled as `dusk.dsk` at the package
root, accessible at `app0:/dusk.dsk` at runtime.

---

## Hardware

| Attribute | Value |
|-----------|-------|
| CPU | ARM Cortex-A9 quad-core, ~444 MHz |
| RAM | 512 MB |
| Display | 960x544 |
| Storage | Vita game card / memory card / internal flash |
| Endian | Little-endian |

---

## Compile-time macros

| Macro | Set |
|-------|-----|
| `DUSK_VITA` | yes |
| `DUSK_SDL2` | yes |
| `DUSK_OPENGL` | yes |
| `DUSK_OPENGL_LEGACY` | yes |
| `DUSK_INPUT_GAMEPAD` | yes |
| `DUSK_PLATFORM_ENDIAN_LITTLE` | yes |
| `DUSK_DISPLAY_WIDTH` | 960 |
| `DUSK_DISPLAY_HEIGHT` | 544 |

No `DUSK_DISPLAY_SIZE_DYNAMIC`, no `DUSK_TIME_DYNAMIC`,
no `DUSK_INPUT_KEYBOARD`, no `DUSK_INPUT_POINTER`,
no `DUSK_NETWORK_IPV6`.

---

## Display

- Fixed 960x544 resolution.
- vitaGL translates OpenGL calls to GXM. Some OpenGL calls are stubbed
  out in `duskplatform.h` where vitaGL does not support them:

  ```c
  #define glDrawArrays(type, first, count)         ((void)0)
  #define glDepthFunc(func)                        ((void)0)
  #define glBlendFunc(sfactor, dfactor)            ((void)0)
  #define glColorTableEXT(...)                     ((void)0)
  ```

  These stubs mean the Vita uses the fixed-function pipeline through
  vitaGL. Do not rely on `glDrawArrays` or depth/blend state changes
  being applied -- use the engine's `displaystate_t` flags instead
  (see `.claude/display-shader.md`).
- `DUSK_OPENGL_LEGACY` is set. Avoid shader-based features that are
  not in the fixed-function ES1 subset.
- Texture dimensions **must** be powers of two.

---

## Asset loading

`dusk.dsk` is bundled inside the `.vpk` and mounted at `app0:/` by the
Vita OS. The asset system opens it at the fixed path:

```c
#define ASSET_VITA_DSK_PATH "app0:/" ASSET_FILE_NAME
```

No path search is needed -- the file is always at that location.

---

## Input

Uses SDL2 with Vita button mapping. Buttons map to SDL2 gamepad
constants:

| Vita button | SDL2 constant |
|-------------|---------------|
| Triangle | `SDL_CONTROLLER_BUTTON_Y` |
| Cross | `SDL_CONTROLLER_BUTTON_A` |
| Circle | `SDL_CONTROLLER_BUTTON_B` |
| Square | `SDL_CONTROLLER_BUTTON_X` |
| Start | `SDL_CONTROLLER_BUTTON_START` |
| Select | `SDL_CONTROLLER_BUTTON_BACK` |
| D-pad | `SDL_CONTROLLER_BUTTON_DPAD_*` |
| L / R | `SDL_CONTROLLER_BUTTON_LEFTSHOULDER / RIGHTSHOULDER` |
| L-Stick | `SDL_CONTROLLER_AXIS_LEFTX/Y` |

Vita also has L2, R2, L3, R3 and touch surfaces -- not currently wired
into the input system.

---

## Save system

Uses `SceIofilemgr` (Vita filesystem API) for file I/O. Save data lives
in the application's sandbox on the memory card. The stream API
(`savestream_t`) handles all serialization with automatic CRC32 and
little-endian encoding (see `.claude/save.md`).

---

## Network

No network implementation exists in `src/duskvita/`. Network
functionality is not currently available on Vita.

---

## Time

No `src/duskvita/time/` directory exists -- the Vita time implementation
falls back to the SDL2 time layer if available, or is not yet
implemented.

---

## Build and toolchain

Requires the [VITASDK](https://vitasdk.org/). Set `VITASDK` in your
environment before configuring.

```sh
cmake -B build \
      -DDUSK_TARGET_SYSTEM=vita \
      -DCMAKE_TOOLCHAIN_FILE=$VITASDK/share/vita.cmake \
      -DCMAKE_BUILD_TYPE=Release
cmake --build build
```

Post-build output: `Dusk.self` (signed executable) and `Dusk.vpk`
(installable package containing the SELF + `dusk.dsk`).

Title ID: `DUSK00001` (configurable via `VITA_TITLEID`).

Dependencies: SDL2, vitaGL, mathneon, vitashark, kubridge, SceGxm,
SceCtrl, SceAudio, SceTouch, SceRtc, SceAppUtil, zip, bz2, z, lzma.

---

## Endianness

Little-endian. `DUSK_PLATFORM_ENDIAN_LITTLE` is set at compile time.

---

## Gotchas

- vitaGL stubs several OpenGL calls. Always use the engine display state
  API rather than calling `glBlendFunc` / `glDepthFunc` directly.
- `DUSK_TIME_DYNAMIC` is not set -- all ticks are fixed-step 16 ms.
- Threading: `pthread` is linked but `DUSK_THREAD_PTHREAD` is not
  explicitly defined in `vita.cmake`. Verify threading behaviour before
  relying on it.
- The Vita implementation is less complete than Linux and PSP -- network
  and time platform layers are absent. Contributions welcome.