Merge branch 'master' of github.com:Lameguy64/PSn00bSDK into latest-commit

1 files changed, 82 insertions, 0 deletions

diff --git a/examples/README.md b/examples/README.md
new file mode 100644
index 0000000..dfea465
--- /dev/null
+++ b/examples/README.md
@@ -0,0 +1,82 @@
+
+# PSn00bSDK Example Programs
+
+## Examples summary
+
+The following list is a brief summary of all the example programs included.
+Additional information may be found in the source code of each example.
+
+| Path                                           | Description                                           | Type | Notes |
+| :--------------------------------------------- | :---------------------------------------------------- | :--: | :---: |
+| [`beginner/cppdemo`](./beginner/cppdemo)       | Simple demonstration of (dynamic) C++ classes         | EXE  |       |
+| [`beginner/hello`](./beginner/hello)           | The obligatory "Hello World" example program          | EXE  |       |
+| [`cdrom/cdbrowse`](./cdrom/cdbrowse)           | File browser using libpsxcd's directory functions     | CD   |       |
+| [`cdrom/cdxa`](./cdrom/cdxa)                   | CD-XA ADPCM audio player                              | CD   |   1   |
+| [`demos/n00bdemo`](./demos/n00bdemo)           | The premiere demonstration program of PSn00bSDK       | EXE  |       |
+| [`graphics/balls`](./graphics/balls)           | Draws colored balls bouncing around the screen        | EXE  |       |
+| [`graphics/billboard`](./graphics/billboard)   | Demonstrates how to draw 2D sprites in a 3D space     | EXE  |       |
+| [`graphics/fpscam`](./graphics/fpscam)         | First-person perspective camera with look-at          | EXE  |       |
+| [`graphics/gte`](./graphics/gte)               | Displays a rotating cube using GTE macros             | EXE  |       |
+| [`graphics/hdtv`](./graphics/hdtv)             | Demonstrates anamorphic widescreen at 704x480         | EXE  |       |
+| [`graphics/render2tex`](./graphics/render2tex) | Procedural texture effects using off-screen drawing   | EXE  |       |
+| [`graphics/rgb24`](./graphics/rgb24)           | Displays a 640x480 24-bit RGB image                   | EXE  |       |
+| [`graphics/tilesasm`](./graphics/tilesasm)     | Drawing a tile-map with assembly language             | EXE  |       |
+| [`io/pads`](./io/pads)                         | Demonstrates reading controllers via low-level access | EXE  |       |
+| [`io/system573`](./io/system573)               | Konami System 573 (PS1-based arcade board) example    | CD   |       |
+| [`lowlevel/cartrom`](./lowlevel/cartrom)       | ROM firmware for cheat devices written using GNU GAS  | ROM  |   2   |
+| [`sound/spustream`](./sound/spustream)         | Custom (non XA) CD-ROM audio streaming using the SPU  | CD   |   1   |
+| [`sound/vagsample`](./sound/vagsample)         | Demonstrates playing VAG sound files with the SPU     | EXE  |       |
+| [`system/childexec`](./system/childexec)       | Loading a child program and returning to parent       | EXE  |       |
+| [`system/console`](./system/console)           | TTY based text console that interrupts gameplay       | EXE  |       |
+| [`system/dynlink`](./system/dynlink)           | Demonstrates dynamically linked libraries             | CD   |       |
+| [`system/timer`](./system/timer)               | Demonstrates using hardware timers with interrupts    | EXE  |       |
+| [`system/tty`](./system/tty)                   | Using TTY as a remote text console interface          | EXE  |       |
+
+Notes:
+
+1. `cdrom/cdxa` and `sound/spustream` do not come with example audio files. In
+   order to run these examples you'll have to provide your own files (and, in
+   the case of `spustream`, convert them using the included Python script) and
+   build the CD image manually.
+2. The `lowlevel/cartrom` example is outdated and does not use SDK libraries.
+   It is kept for reference purposes only.
+
+## Building the examples
+
+The instructions below assume that PSn00bSDK, CMake 3.20+ and a GCC toolchain
+are already installed. Refer to the [installation guide](../doc/installation.md)
+for details.
+
+**NOTE**: all examples are compiled by default when building the PSn00bSDK
+libraries and tools (check the `build/examples` directory). These instructions
+are for rebuilding the examples *after* the SDK has been installed.
+
+1. Copy the contents of this directory (`share/psn00bsdk/examples` within the
+   PSn00bSDK installation directory) to your home directory or to another
+   folder you have write access to.
+
+2. Configure and build the examples by running:
+
+   ```bash
+   cmake -S . -B ./build -G "Ninja" -DCMAKE_TOOLCHAIN_FILE=<INSTALL_PATH>/lib/libpsn00b/cmake/sdk.cmake
+   cmake --build ./build
+   ```
+
+   Replace `<INSTALL_PATH>` with the installation prefix you chose when
+   installing the SDK (usually `C:\Program Files\PSn00bSDK` or `/usr/local`,
+   so the full path to `sdk.cmake` would be
+   `C:\Program Files\PSn00bSDK\lib\libpsn00b\cmake\sdk.cmake` or
+   `/usr/local/lib/libpsn00b/cmake/sdk.cmake` respectively).
+
+   Add `-DPSN00BSDK_TARGET=mipsel-unknown-elf` to the first command if your
+   toolchain targets `mipsel-unknown-elf` rather than `mipsel-none-elf`. If you
+   can't get Ninja to work or don't have it installed, you can also replace
+   `-G "Ninja"` with `-G "Unix Makefiles"` (`-G "MSYS Makefiles"` on Windows)
+   to build using `make` instead.
+
+   This should create a `build` directory whose structure mirrors the one of
+   the parent directory, with each subfolder containing built executables and
+   CD images for each example.
+
+-----------------------------------------
+_Last updated on 2022-01-17 by spicyjpeg_