{"id":16854958,"url":"https://github.com/badlogic/r96","last_synced_at":"2025-08-01T23:34:40.972Z","repository":{"id":64508106,"uuid":"572251681","full_name":"badlogic/r96","owner":"badlogic","description":"Repository for the blog post series \"Rendering like it's 1996\"","archived":false,"fork":false,"pushed_at":"2023-01-28T19:30:42.000Z","size":1466,"stargazers_count":131,"open_issues_count":0,"forks_count":4,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-04-02T03:51:15.514Z","etag":null,"topics":["emscripten","game-development","game-engine","game-engine-framework","graphics-programming","webassembly"],"latest_commit_sha":null,"homepage":"https://marioslab.io","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/badlogic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-11-29T21:45:46.000Z","updated_at":"2025-03-04T16:20:22.000Z","dependencies_parsed_at":"2023-02-15T18:31:37.275Z","dependency_job_id":null,"html_url":"https://github.com/badlogic/r96","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/badlogic/r96","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/badlogic%2Fr96","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/badlogic%2Fr96/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/badlogic%2Fr96/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/badlogic%2Fr96/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/badlogic","download_url":"https://codeload.github.com/badlogic/r96/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/badlogic%2Fr96/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268311992,"owners_count":24230493,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-01T02:00:08.611Z","response_time":67,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["emscripten","game-development","game-engine","game-engine-framework","graphics-programming","webassembly"],"created_at":"2024-10-13T13:57:53.115Z","updated_at":"2025-08-01T23:34:40.946Z","avatar_url":"https://github.com/badlogic.png","language":"C","readme":"# r96\n![](tools/docs/screenshot.png)\nRepository for the blog post series [\"Rendering like it's 1996\"](https://marioslab.io/posts/rendering-like-its-1996/babys-first-pixel). The series walks you through building various software rasterization techniques as used in PC games and demos of the 90ies, while using \"modern\" technologies.\n\nThe code is written using C99 and can be run out of the box on Windows, Linux, macOS, web browsers with WASM support, and DOS, e.g. DOSBox, FreeDOS running in VirtualBox, or actual DOS hardware with support for VESA.\n\nThe rasterization code itself is platform agnostic and should compile for any platform. The demos use a fork of [MiniFB](https://github.com/badlogic/MiniFB) to open a window, draw pixels to it, process input events, and query a high-precision timer.\n\n[View the demos in your browser](https://marioslab.io/projects/r96/).\n\n## Installing required tools\nTo compile this project for the desktop, web, and DOS, install these dependencies first:\n\n* [Visual Studio Code](https://code.visualstudio.com/)\n    * Ensure Visual Studio Code is available on the command line via the `code` command. This is the default on Windows and Linux. On macOS, press `CMD+SHIFT+P`, type `Shell Command: Install 'code' command in PATH`, and press enter.\n* **Windows**\n    * [Git for Windows](https://git-scm.com/download/win). Make sure its available on the command line via the system PATH. It's an option during installation.    \n* **macOS**\n    * [XCode](https://developer.apple.com/xcode/). Make sure to also install the [command line tools](https://mac.install.guide/commandlinetools/4.html)\n    * [Homebrew](https://brew.sh/)\n* **Linux**\n    * Git, [GCC](https://gcc.gnu.org/), [GDB](https://www.sourceware.org/gdb/), Python, and x11-dev E.g. Ubuntu/Debian: `sudo apt install git build-essential gdb python x11-dev`\n\nAfter successful installation, open a shell (or Git Bash on Windows), and run the `tools/download-tools.sh` script. It will download the remaining dependencies. On Linux, you may be prompted to install additional packages via your package manager.\n\nYou can now open the project in VS Code, or build and run it via the command line.\n\n\u003e **Note:** the first time you open a source file in VS Code, you may be asked to install the `clangd` server. Just click `Yes` in the notification to do so.\n\n## Building and running in VS Code\n\n\u003cvideo src=\"https://user-images.githubusercontent.com/514052/211121019-a795af7c-983c-4bdb-b884-6336b8f9aa14.mp4\" autoplay=true loop=true controls=true\u003e\u003c/video\u003e\n\nThe video demonstrates tools installation, building, and debugging for all supported platforms (desktop, web, DOS).\n\n### Building\nThe project uses [CMake](https://cmake.org/) as the build system. For each supported target platform, the build defines a [CMake configure preset](CMakePresets.json) which will build the code in debug and release mode for the selected target platform. When you first open the `r96` folder in VS Code, you'll be asked to select a configure preset.\n\n![](tools/docs/preset.png)\n\nGoing with `Desktop debug` is a good starting point. You can switch the configure preset via the corresponding status bar entry.\n\n![](tools/docs/change-preset.png)\n\nYou can now press the `Build` button in the status bar whenever you want to build the project for the specified configuration.\n\n![](tools/docs/build.png)\n\nThis will (incrementally) rebuild the code for the select platform. The resulting build output consisting of executables and assets can be found in `build/\u003cos\u003e-debug`. E.g. for Windows `build/windows-debug`, for macOS `build/macos-debug`, for DOS `build/dos-debug` and so on. When building a release preset, the output can be found in `build/\u003cos\u003e-release`.\n\nTo learn more about how to use VS Code CMake integration, check out the [documentation](https://vector-of-bool.github.io/docs/vscode-cmake-tools/index.html).\n\n### Debugging and running\nThe project comes with a [`.vscode/launch.json`](.vscode/launch.json) file which defines launch configurations for each platform. Click the launch button in the status bar to select the launch configuration and start a debugging session:\n\n![](tools/docs/launch.png)\n\nAfter clicking this status bar entry, you'll be asked to select a launch configuration:\n\n![](tools/docs/launch-configs.png)\n\nWhen you first start a debugging session, you'll be asked to select a launch target:\n\n![](tools/docs/launch-target.png)\n\nYou can also change the launch target in the status bar:\n\n![](tools/docs/launch-target-status-bar.png)\n\nAfter selecting the launch target, the code is incrementally rebuild, and the debugging session starts. \n\nInstead of going through the status bar, you can also start a new debugging sessions by pressing `F5`. This will launch a session for the currently selected launch configuration, preset, and launch target.\n\n\n**Important:** the launch configuration MUST match the preset you selected:\n\n* `Desktop debug target`: select the `Desktop debug` or `Desktop release` preset.\n* `Web debug target`: select the `Web debug` or `Web release` preset.\n* `DOS debug target`: select `DOS debug` preset.\n* `DOS run target`: select the `DOS release` preset. This will run the program in DOSBox-x without attaching a debugger.\n\nEach supported platform behaves a bit different to the others when debugging.\n\n#### Desktop\nThis is the standard debugging experience you are used to. Set breakpoints and watches, interrupt the program at any time, and so on.\n\n#### Web\nDebugging the C code compiled to WASM directly in VS Code is not possible. When you start a web debugging session, the respective launch configuration starts a local static file server and opens the `.html` file corresponding to the selected launch target in a browser tab.\n\nWhen you are done \"debugging\", close the browser tab, and close the debugging session in VS Code by clicking the \"Stop\" button in the debugger controls.\n\n If you feel adventurous: it is possible to [debug the C and JavaScript code it in Chrome](https://marioslab.io/posts/rendering-like-its-1996/babys-first-pixel/#Can%20I%20debug%20the%20C%20code%20in%20the%20browser?) when building with the `Web debug` preset.\n\n#### DOS\nFor debugging to work in DOS, you need to integrate the [GDB stub](https://sourceware.org/gdb/onlinedocs/gdb/Remote-Stub.html) that is found in [`src/dos/gdbstub.h`](src/dos/gdbstub.h) with the program. The general structure will look like this.\n\n```c\n#define GDB_IMPLEMENTATION\n#include \"gdbstub.h\"\nint main(void) {\n    gdb_start();\n    ... setup code ...\n    do {\n        ... main loop ...\n        gdb_checkpoint();\n    } while (mfb_wait_sync(window));\n}\n```\n\nThe [12_hello_dos.c](src/12_hello_dos.c) demo is an example on how to integrate the GDB stub.\n\nThe first two lines will pull in the implementation of the GDB stub. \n\nThe call to `gdb_start()` will setup some GDB stub internals, then wait for the debugger to connect. Once the debugger is connected, you can set breakpoints, step, or resume the program. If a breakpoint is hit, the GDB stub will take control of the program again, and talk to the debugger, until the debugger tells the stub to step or resume.\n\nFinally, the call to `gdb_checkpoint()` at the end of the main loop gives the debugger a chance to tell the stub to interrupt the program.\n\nWhen you are done with debugging, close DOSBox-x and close the debugging session in VS Code by clicking the \"Stop\" button in the debugger controls. You will not be able to start a new DOS debugging session unless the DOSBox-x window of a previous session is closed.\n\n\u003e If the debugger gets stuck on start, or during debugging, close DOSBox-x, then in VS Code, open the command palette and execute `Debug: Stop`.\n\n## Building and running on the command line\n### Desktop\nTo build for your operating system in release mode:\n```\ncmake --preset \u003cos\u003e-release\ncmake --build build/\u003cos\u003e-release\n```\n\nValid values for `\u003cos\u003e` are `windows`, `linux`, and `macos`. E.g. on Windows:\n\n```\ncmake --preset windows-release\ncmake --build build/windows-release\n````\n\nThe resulting executables for each demo app and the copied `assets/` folder can then be found in the `build/\u003cos\u003e-release` directory. You can run them directly on your host system.\n\nTo build for your operating system in debug mode:\n```\ncmake --preset \u003cos\u003e-debug\ncmake --build build/\u003cos\u003e-debug\n```\n\nThe resulting executables and assets will end up in the `build/\u003cos\u003e-debug` directory.\n\nYou can either run the executables as is, or you can debug them with [LLDB](https://lldb.llvm.org/) (Windows, macOS) or [GDB](https://www.sourceware.org/gdb/) (Linux) on the command line.\n\n### Web\nTo build for the web in release mode:\n```\ncmake --preset web-release\ncmake --build build/web-release\n```\n\nThis will generate a `.js` and `.wasm` file for each executable in `build/web-release`, as well as copy over the corresponding `.html` file from the `src/web` folder and `assets/` to `build/web-release`. \n\nTo run the demos in your browser execute:\n\n```\n./tools/web/static-server build/web-release 8000\n```\n\nA workflow for web development is to leave the web server running, rebuild the project on source code changes and refresh the demo page in the browser.\n\nTo build for the web in debug mode:\n\n```\ncmake --preset web-debug\ncmake --build build/web-debug\n```\n\nThe resulting `.js`, `.wasm`, and `.html` files as well as the assets will end up in `build/web-debug`.\n\nTo run the debuggable demos in your browser execute:\n\n```\n./tools/web/static-server build/web-debug 8000\n```\n\nYou can [debug both the JavaScript and C code in Chrome](https://developer.chrome.com/blog/wasm-debugging-2020/).\n\n### DOS\nTo build for DOS in release mode:\n\n```\ncmake --preset dos-release\ncmake --build build/dos-release\n```\n\nThe resulting executables for each demo app and the assets can then be found in the `build/dos-release` directory. You can run them via DOSBox-x like this:\n\n```\n./tools/dos/dosbox-x/dosbox-x -fastlaunch -exit -conf ./tools/dos/dosbox-x.conf build/dos-release/\u003cexecutable-file.exe\u003e\n```\n\nTo build for DOS in debug mode:\n\n```\ncmake --preset dos-debug\ncmake --build build/dos-debug\n```\n\nThe resulting executables and assets can be found in `build/dos-debug`.\n\nYou can debug the executables running in DOSBox-x. Make sure to integrate the [GDB stub](https://sourceware.org/gdb/onlinedocs/gdb/Remote-Stub.html) that is found in [`src/dos/gdbstub.h`](src/dos/gdbstub.h) like this:\n\n```c\n#define GDB_IMPLEMENTATION\n#include \"gdbstub.h\"\nint main(void) {\n    gdb_start();\n    ... setup code ...\n    do {\n        ... main loop ...\n        gdb_checkpoint();\n    } while (mfb_wait_sync(window));\n}\n```\n\nThe [12_hello_dos.c](src/12_hello_dos.c) demo is an example on how to integrate the GDB stub.\n\nRun the executable in DOSBox-x:\n\n```\n./tools/dos/dosbox-x/dosbox-x -fastlaunch -exit -conf ./tools/dos/dosbox-x.conf build/dos-debug/\u003cexecutable-file.exe\u003e\n```\n\nThe app will wait in `gdb_start()` for the debugger to connect.\n\nStart GDB for DOS, load the debug info from the executable, and let it connect to the app running in DOSBox-x:\n\n```\n./tools/dos/gdb/gdb\n(gdb) file build/dos-debug/\u003cexecutable-file.exe\u003e\n(gdb) target remote localhost:5123\n```\n\nGDB will connect and stop in `gdb_start()`. You can now set breakpoints, step, continue, inspect local variables and so on.\n\n### What does the `tools/download-tools.sh` script install?\nThe following dependencies will be installed. Some will be installed on a system level, others will be stored in `tools/\u003cplatform\u003e`.\n\n* Desktop\n    * [CMake](https://cmake.org/), a high-level build system. (system-level)\n    * [Ninja](https://ninja-build.org/), a lower-level build system, invoked by CMake. (system-level)\n    * VS Code extensions for C/C++ development (system-level)\n        * [C/C++ Extension Pack](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools-extension-pack), provides C/C++ debugging, CMake support, and bad intellisense, which is disabled in `.vscode/settings.json`\n        * [clangd](https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd), provides good intellisense.\n        * [Native Debug extension](https://marketplace.visualstudio.com/items?itemName=webfreak.debug), needed to debug programs running in DOSBox-x.\n* Web\n    * [Python](https://www.python.org/), required by Emscripten. (system-level)\n    * [Static file server](https://github.com/badlogic/static-file-server), a zero-dependecy, self-contained static file server used when working on WASM code. (`tools/web/`)\n    * [Emscripten](https://emscripten.org/), a Clang-based toolchain to compile C/C++ to WASM. (`tools/web/`)\n* DOS\n    * [GDB 7.1a](https://github.com/badlogic/gdb-7.1a-djgpp), a fork of GDB specifically for debugging 32-bit protected mode DOS applications remotely. (`tools/dos/gdb`)\n    * [DJGPP](https://www.delorie.com/djgpp/), a GCC-based toolchain to compile C/C++ to 32-bit protected mode DOS applications (Quake was built with this). (`tools/dos/djgpp`)\n    * [DOSBox-x](https://github.com/badlogic/dosbox-x), a DOS emulator. This is a fork that fixes a few things to remotely debugging DJGPP-based programs works. (`tools/dos/dosbox-x`)\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbadlogic%2Fr96","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbadlogic%2Fr96","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbadlogic%2Fr96/lists"}