diff options
| -rw-r--r-- | .github/workflows/documentation.yaml | 29 | ||||
| -rw-r--r-- | README.md | 6 | ||||
| -rw-r--r-- | docs/Contributing/c-coding-style.md | 13 | ||||
| -rw-r--r-- | docs/Contributing/naming.md | 29 | ||||
| -rw-r--r-- | docs/getting-started.md | 7 | ||||
| -rw-r--r-- | docs/index.md | 42 | ||||
| -rw-r--r-- | docs/project-layout.md | 9 | ||||
| -rw-r--r-- | docs/rendering.md | 7 | ||||
| -rw-r--r-- | mkdocs.yaml | 3 |
9 files changed, 145 insertions, 0 deletions
diff --git a/.github/workflows/documentation.yaml b/.github/workflows/documentation.yaml new file mode 100644 index 0000000..91cb81d --- /dev/null +++ b/.github/workflows/documentation.yaml @@ -0,0 +1,29 @@ +name: ci +on: + push: + branches: + - master + - main +permissions: + contents: write +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Configure Git Credentials + run: | + git config user.name github-actions[bot] + git config user.email 41898282+github-actions[bot]@users.noreply.github.com + - uses: actions/setup-python@v5 + with: + python-version: 3.x + - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV + - uses: actions/cache@v4 + with: + key: mkdocs-material-${{ env.cache_id }} + path: .cache + restore-keys: | + mkdocs-material- + - run: pip install mkdocs-material + - run: mkdocs gh-deploy --force @@ -20,3 +20,9 @@ All third-party dependencies are licensed under their own license. * Lint (no change) `find src/ -iname *.h -o -iname *.c | xargs clang-format --style=file --dry-run --Werror` * Format (edit in place) `find src/ \( -iname "*.h" -o -iname "*.c" \) | xargs clang-format -i --style=file` * `clang-format` must be installed! +* Documentation + * serve mkdocs locally + * `docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material` + + * Build docs static site + * `docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material build` diff --git a/docs/Contributing/c-coding-style.md b/docs/Contributing/c-coding-style.md new file mode 100644 index 0000000..4e268cc --- /dev/null +++ b/docs/Contributing/c-coding-style.md @@ -0,0 +1,13 @@ +--- +title: C Coding Style +--- + +A lot of these should be forced onto you by `clang-format` and `clang-tidy` but for posterity here are +a few of the styles that we stick to. + +* **Pointer next to type** - we use `type* variable` in function signatures and variable declarations e.g. `mat4* model` + + +## Memory + +### Arena allocation diff --git a/docs/Contributing/naming.md b/docs/Contributing/naming.md new file mode 100644 index 0000000..518c22e --- /dev/null +++ b/docs/Contributing/naming.md @@ -0,0 +1,29 @@ +--- +title: Naming Conventions +--- + +#### 1. Prefer SOV function names + +Prefer SOV Subject Object Verb naming for functions. + +This makes it very easy to find the functions you want with autocomplete and maintain a consistent naming convention +throughout the codebase. + +e.g. + +* `renderer_frame_begin` +* `engine_tick_begin` +* `texture_data_load` + +--- + +#### 2. Long-running systems + +systems that run for the lifetime of the application or for a very long time should have: + +* `bool system_init(system_state* state)` a `init` function +* `void system_shutdown(system_state* state)` and a `shutdown` function + +--- + +#### 3. TODO
\ No newline at end of file diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000..0baf21c --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,7 @@ +--- +title: Getting up and running +--- + +The main build tool we use is [xmake](https://xmake.io/#/getting_started) so installing that is the main prerequisite. + +Once that is installed you *should* be able to simply run `xmake build` in the top-level directory.
\ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..54d6383 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,42 @@ +# Welcome to Celeritas + +Welcome to the Celeritas Game Engine's documentation! + +## What is it? + +Celeritas is a small 3D game engine written in plain ol' C **and** OCaml. + +The idea underlying celeritas is to have a small versatile "core" that can then be added to from other languages. +This means you could add gameplay systems in OCaml but rely on the celeritas core layer to do all the heavy lifting +when it comes to computation or rendering. I will be providing ocaml bindings to the C API but implementing Lua bindings for example +would be fairly trivial. + +**What does 'celeritas' mean?** + +Celerity is an English word meaning "alacrity" "swiftness". +Celeritas is the original Latin word for celerity that the English is derived from. + +## Feature Set + +**Implemented (core)** + +* Vulkan & OpenGL renderer backends (*need to port Metal renderer over*) +* Basic Blinn-Phong lighting model (*need to port from old project*) +* Task queue for loading mesh and texture data into memory on background threads + +**In-progress** + +* Skeletal animation + +**Roadmap going forwards** + +* Collision detection +* Terrain rendering +* GPU-driven rendering + +## Getting started + +Check these pages out + +* [Getting started](getting-started.md) +* [Project layout](project-layout.md)
\ No newline at end of file diff --git a/docs/project-layout.md b/docs/project-layout.md new file mode 100644 index 0000000..74a84aa --- /dev/null +++ b/docs/project-layout.md @@ -0,0 +1,9 @@ +--- +title: Project Layout +--- + +``` +deps/ - third-party dependencies +docs/ - these docs you're reading now that get built with mkdocs +TODO: the rest... +```
\ No newline at end of file diff --git a/docs/rendering.md b/docs/rendering.md new file mode 100644 index 0000000..05da5fc --- /dev/null +++ b/docs/rendering.md @@ -0,0 +1,7 @@ +# Rendering + +Rendering is split into 3 'registers'. + +1. **RAL** (Render Abstraction Layer) - thin abstraction over graphics APIs +2. **render** - implements the default renderer and higher-level functions like `draw_scene` +3. **immediate** - immediate-mode drawing API for things like debug visualisation and UI
\ No newline at end of file diff --git a/mkdocs.yaml b/mkdocs.yaml new file mode 100644 index 0000000..b15a94b --- /dev/null +++ b/mkdocs.yaml @@ -0,0 +1,3 @@ +site_name: Celeritas Engine +theme: + name: material
\ No newline at end of file |