Example freegnm programs

This repository holds programs to show how to use opengnm: a clean-rewrite GPU library for the PlayStation 4, and opengnm-psbc: a SPIR-V to PS4 Shader Binary compiler. The original freegnm and psbc libraries are also supported.

These samples are meant to be as simple and straightforward as possible.

NOTES:

• None of these examples were tested on a Pro/NEO PS4 and may not work there.

Examples available

Triangle

Very basic example of the GPU's capabilities.

The ps4-freegnm parent workspace provides tools/build_triangle_pkg.sh and tools/stage_triangle_pkg.sh wrappers for hardware validation. They build the local psbc shader compiler in the OpenOrbis Docker environment, package the OpenOrbis runtime modules, and stage the resulting FGNM00000 package over FTP.

The triangle executable has an opt-in opengnm migration path:

make USE_OPENGNM=1 tri

The Eden composite blit executable has the same style of opengnm path:

make USE_OPENGNM=1 eden_composite_blit

The Eden composite DMA executable also links through opengnm:

make USE_OPENGNM=1 eden_composite_dma

The Eden triangle wrapper C++ executable also links through opengnm:

make USE_OPENGNM=1 eden_triangle_wrapper

These paths link against ../../opengnm/libopengnm.a and use opengnm's source-only gnm*/gpa* compatibility headers for core GNM calls. Legacy GNF/PSSL metadata headers still come from ../../freegnm until those tool-layer types move to opengnm's split tools.

Primitives

Shows the unique primitive types available in the PS4 hardware.

Cube

Draws a 3D textured cube.

GLTF

Renders a GLTF's model with some basic PBR parameters.

Instances

Example of instanced draw calls usage.

Indirect

Shows how to setup and use indirect draws.

VideoOut Linear

Minimal hardware smoke test for linear sceVideoOutRegisterBuffers plus sceVideoOutSubmitFlip presentation. This sample does not use GNM draw commands; it is intended to isolate VideoOut buffer registration, CPU writes to garlic memory, flip events, and PS4debug process capture before testing the full GPU path.

Eden Composite Smoke

Standalone hardware smoke test for Eden's current CPU presentation bridge. This sample generates a synthetic RGBA8888 framebuffer, converts it through Eden's Tegra block-linear swizzle/unswizzle path, copies it into linear A8B8G8R8_SRGB VideoOut buffers, and flips it as title ID FGNM00007. Build/stage from the parent workspace with tools/build_eden_composite_pkg.sh and tools/stage_eden_composite_pkg.sh.

Eden Composite DMA Smoke

Variant of the Eden composite smoke test that keeps CPU swizzle/unswizzle validation but copies the final linear staging frame into the registered VideoOut buffer with CP DMA_DATA. It runs as title ID FGNM00008 and is the isolated hardware test for RendererGnm's presentation DMA copy path. Build/stage from the parent workspace with tools/build_eden_composite_dma_pkg.sh and tools/stage_eden_composite_dma_pkg.sh.

Eden Composite Blit Smoke

Variant that keeps CPU swizzle/unswizzle validation but uploads the final linear frame as a GNM texture, renders it through a full-screen VS/PS pass into tiled GNM render targets, and flips those render targets through VideoOut. It runs as title ID FGNM00009 and isolates the next GPU presentation step before moving the Tegra block-linear address math into shader code. Build/stage from the parent workspace with tools/build_eden_composite_blit_pkg.sh and tools/stage_eden_composite_blit_pkg.sh.

Eden Composite Shader Decode Smoke

Variant that removes the CPU unswizzle from the blit smoke. It CPU-generates and Tegra-swizzles the same synthetic framebuffer, binds the block-linear guest framebuffer as an R32_UINT pixel-shader buffer, decodes the Tegra address in shader code, and renders into tiled GNM render targets for VideoOut. It runs as title ID FGNM00010 and isolates shader-side buffer resource binding plus block-linear address decoding. Build/stage from the parent workspace with tools/build_eden_composite_shader_pkg.sh and tools/stage_eden_composite_shader_pkg.sh.

Eden Renderer Present Smoke

Validation package for Eden's renderer_gnm shader-decode presentation bridge. It builds one synthetic Tegra block-linear source frame, updates only a small top marker band directly in tiled memory each frame, presents through the shared Eden presenter, and writes into VideoOut buffers only after the GNM wait-safe command. It runs as title ID FGNM00013 and isolates GPU-side decode/present cost plus small tiled updates from full-frame CPU block-linear generation. The bridge also checks the same supported-framebuffer selection rule as RendererGnm through the shared gnm_present_selection helper: supported shapes must use shader-decode direct staging and do not fall back to CPU unswizzle/DMA if that path fails. Build/stage from the parent workspace with tools/build_eden_renderer_present_pkg.sh and tools/stage_eden_renderer_present_pkg.sh.

Building

You need the following tools to build the projects:

• Clang
• glslc from shaderc
• GNU Make
• LLD linker
• OpenOrbis Toolchain
• opengnm-psbc (or psbc)

Then go to one of the example's directory, and run

export OO_PS4_TOOLCHAIN=/path/to/OpenOrbis-PS4-Toolchain
make

References

Some of the samples are based on Vulkan samples from Sascha Willems.

Some PBR algorithms are taken from Moving Frostbite to Physically Based Rendering.

Libraries and resources

The following libraries are used:

• cglm, MIT license
• cgltf, MIT license
• Nuklear, Public Domain or MIT license
• stb_image and stb_truetype, Public Domain or MIT license

The following resources are used:

• Stanford dragon by Stanford Computer Graphics Laboratory, non-commercial use only
• Hack typeface by SourceFoundry, MIT license
• Screenshots of Dark Knight Rises film's plane scene

The libraries and resources are owned by their respective owners and are not covered by this project's license.

License

This project is licensed under the MIT License, see LICENSE. Vendored third-party libraries (cgltf, Nuklear, stb) retain their original licenses.