diff --git a/book/.gitignore b/book/.gitignore new file mode 100644 index 0000000..7585238 --- /dev/null +++ b/book/.gitignore @@ -0,0 +1 @@ +book diff --git a/book/book.toml b/book/book.toml new file mode 100644 index 0000000..c82a014 --- /dev/null +++ b/book/book.toml @@ -0,0 +1,6 @@ +[book] +authors = ["marceline-cramer"] +language = "en" +multilingual = false +src = "src" +title = "Canary GUI Book" diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md new file mode 100644 index 0000000..88f08b1 --- /dev/null +++ b/book/src/SUMMARY.md @@ -0,0 +1,30 @@ +# Summary + +[Introduction](introduction.md) +[History](history.md) + +- [Implementation](impl/README.md) + - [Development Process](impl-rs/process.md) + - [Usage](impl-rs/usage.md) + - [Backends](impl-rs/backends.md) + - [Examples](impl-rs/examples.md) +- [Ecosystem](ecosystem/README.md) + - [Messages](ecosystem/messages.md) + - [Protocols](ecosystem/protocols.md) + - [Finding Scripts](ecosystem/finding-scripts.md) + - [Fonts](ecosystem/fonts.md) + - [Localization](ecosystem/localization.md) +- [Rendering](rendering/README.md) + - [Graphics State](rendering/state.md) + - [Primitives](rendering/primitives.md) + - [Canvases](rendering/canvases.md) + - [Tessellation](rendering/tessellation.md) + - [Text](rendering/text.md) +- [Input](input/README.md) + - [Pointer](input/pointer.md) + - [Text](input/text.md) + +--- + +[Glossary](glossary.md) +[Credits](credits.md) diff --git a/book/src/credits.md b/book/src/credits.md new file mode 100644 index 0000000..e94d007 --- /dev/null +++ b/book/src/credits.md @@ -0,0 +1 @@ +# Credits diff --git a/book/src/ecosystem/README.md b/book/src/ecosystem/README.md new file mode 100644 index 0000000..e46e912 --- /dev/null +++ b/book/src/ecosystem/README.md @@ -0,0 +1 @@ +# Ecosystem diff --git a/book/src/ecosystem/finding-scripts.md b/book/src/ecosystem/finding-scripts.md new file mode 100644 index 0000000..a2c0fdf --- /dev/null +++ b/book/src/ecosystem/finding-scripts.md @@ -0,0 +1 @@ +# Finding Scripts diff --git a/book/src/ecosystem/fonts.md b/book/src/ecosystem/fonts.md new file mode 100644 index 0000000..da8e1b8 --- /dev/null +++ b/book/src/ecosystem/fonts.md @@ -0,0 +1 @@ +# Fonts diff --git a/book/src/ecosystem/localization.md b/book/src/ecosystem/localization.md new file mode 100644 index 0000000..d0c0355 --- /dev/null +++ b/book/src/ecosystem/localization.md @@ -0,0 +1 @@ +# Localization diff --git a/book/src/ecosystem/messages.md b/book/src/ecosystem/messages.md new file mode 100644 index 0000000..fbebf53 --- /dev/null +++ b/book/src/ecosystem/messages.md @@ -0,0 +1 @@ +# Messages diff --git a/book/src/ecosystem/protocols.md b/book/src/ecosystem/protocols.md new file mode 100644 index 0000000..8d9f731 --- /dev/null +++ b/book/src/ecosystem/protocols.md @@ -0,0 +1 @@ +# Protocols diff --git a/book/src/glossary.md b/book/src/glossary.md new file mode 100644 index 0000000..ca3c827 --- /dev/null +++ b/book/src/glossary.md @@ -0,0 +1 @@ +# Glossary diff --git a/book/src/history.md b/book/src/history.md new file mode 100644 index 0000000..4932688 --- /dev/null +++ b/book/src/history.md @@ -0,0 +1,16 @@ +# History + +Canary was originally conceived in early 2021 as a WebAssembly-based, +minimalistic UI framework during the development of [Mondradiko](https://mondradiko.github.io), +where it was a dedicated subsystem of a larger game engine. When the new UI +system turned out to be even more powerful than originally expected, it was +decided that the UI code would be broken out into a separate project. The +Mondradiko community voted to name it "Canary" (the other contenders were +"Robin" and "Magpie"), and it was given [a new repository](https://github.com/mondradiko/canary). +However, before Canary could be fully fleshed-out, development on Mondradiko +was ceased and there was no reason to continue working on Canary. + +In mid-2022, development was started back up, as a member project of +[Tebibyte Media](https://tebibyte.media). This new community of free software +enthusiasts had new interest in Canary apart from its usage in a larger game +engine, so development was restarted. diff --git a/book/src/impl-rs/backends.md b/book/src/impl-rs/backends.md new file mode 100644 index 0000000..817deab --- /dev/null +++ b/book/src/impl-rs/backends.md @@ -0,0 +1 @@ +# Backends diff --git a/book/src/impl-rs/examples.md b/book/src/impl-rs/examples.md new file mode 100644 index 0000000..df635b4 --- /dev/null +++ b/book/src/impl-rs/examples.md @@ -0,0 +1 @@ +# Examples diff --git a/book/src/impl-rs/process.md b/book/src/impl-rs/process.md new file mode 100644 index 0000000..2e75489 --- /dev/null +++ b/book/src/impl-rs/process.md @@ -0,0 +1,23 @@ +# Development Process + +# Adding New Features + +To keep Canary as minimal as possible we adopt a conservative policy for what +features are added to its specification. This is to avoid the feature-creep that +plagues large UI and UX frameworks in the long run. The following reasons are +general guidelines for what features should and should not be added to Canary. + +## Reasons to add a feature + +The feature provides a clear benefit to a cultural class of users. For example, +Arabic speakers will require that text can be rendered right-to-left. + +The feature reduces the resource usage of scripts. + +## Reasons NOT to add a feature + +The feature adds more complexity to the host than is removed from scripts. + +The feature only applies to certain host configurations. + +The feature can be effectively emulated in a script. diff --git a/book/src/impl-rs/usage.md b/book/src/impl-rs/usage.md new file mode 100644 index 0000000..0120d1b --- /dev/null +++ b/book/src/impl-rs/usage.md @@ -0,0 +1,95 @@ +# Using `canary-rs` + +[`canary-rs`](https://git.tebibyte.media/canary/canary-rs) is the reference +implementation for Canary. It is written in Rust, and is licensed under the +LGPLv3. + +`canary-rs` is the central hub for Canary's development. It includes host-side +Rust code, helper crates for Canary hosts, wrapper crates for scripts +authored in Rust, and even the source code for the documentation that you're +currently reading. + +`canary-rs` provides a graphical "test harness" that embeds the Canary runtime +into a lightweight graphical app. It has two purposes: first, to give +script authors a playground independent of a larger framework to safely debug, +benchmark, and experiment with their scripts, and second, to give Canary +embedders a live, functioning example of how Canary can be integrated into their +applications. + +# Running the `canary-rs` test harness + +The test harness requires a Canary script to run. If you don't already have one, +you can follow [these instructions](optional-building-the-sword-art-online-demonstration-ui-script) +to build the example script provided by `canary-rs`. + +## Building the test harness + +To build the test harness from source, first make sure that you have +[installed the standard Rust toolchain](https://www.rustlang.org/tools/install), +including `rustup`, `rustc`, and `cargo`, as well as a frontend to +[Git](https://git-scm.com/). This guide assumes that you are using the Git +command-line interface (CLI). + +Next, clone the upstream repository: +```sh +$ git clone https://git.tebibyte.media/canary/canary-rs.git +$ cd canary-rs +``` + +Then, run `cargo` to build the test harness package: +```sh +$ cargo build --release -p canary_egui_harness +``` + +Now, the test harness can be ran with a script: +```sh +$ cargo run --release -p canary_egui_harness -- +``` + +## (Optional) Building the Sword Art Online demonstration UI script + +`canary-rs` provides an example of a fully-functioning script which, optionally, +can be built and loaded into the test harness to ensure its functioning. + +To build it, you must first follow [the instructions above](#building-the-test-harness) +to clone and build the test harness and to set up the Rust toolchain. + +Then, add the `wasm32-unknown-unknown` target so that Rust can compile to +WebAssembly: +```sh +$ rustup target add wasm32-unknown-unknown +``` + +Next, compile the example script: +```sh +$ cargo build --release -p sao-ui-rs --target wasm32-unknown-unknown +``` + +The path to the built example script is `target/wasm32-unknown-unknown/release/sao_ui_rs.wasm`. +Now it can be run using the test harness: +```sh +$ cargo run --release -p canary_egui_harness -- target/wasm32-unknown-unknown/release/sao_ui_rs.wasm +``` + +# Using `canary-rs` as a Rust library + +***WARNING***: `canary-rs` is still in alpha development so both its API and its +version number are unstable. It is not recommended to use it in your own +projects unless you are involved with Canary's development. + +`canary-rs` is not yet available on [crates.io](https://crates.io), so to add it +as a dependency, you must add its [upstream git repository](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#specifying-dependencies-from-git-repositories) +instead: + +```toml +[dependencies] +canary = { git = "https://git.tebibyte.media/canary/canary-rs", rev = "deadbeef" } +``` + +Because `canary-rs` is still under active development, it is recommended to +pull a fixed, specific commit using the `rev` key. That can be a specific tag, +some point in the commit history, or whatever the latest commit on `main` is. + +[Tebibyte Media](https://tebibyte.media) is not capable of hosting rustdocs yet, +so to learn how the API works, you can read the source code for the test +harness, or dig through the source code itself. diff --git a/book/src/impl/README.md b/book/src/impl/README.md new file mode 100644 index 0000000..010cb3d --- /dev/null +++ b/book/src/impl/README.md @@ -0,0 +1,4 @@ +# Implementation + +This chapter discusses the design and usage of [canary-rs](https://git.tebibyte.media/canary/canary-rs), +the canonical implementation of Canary. diff --git a/book/src/input/README.md b/book/src/input/README.md new file mode 100644 index 0000000..135b6af --- /dev/null +++ b/book/src/input/README.md @@ -0,0 +1 @@ +# Input diff --git a/book/src/input/pointer.md b/book/src/input/pointer.md new file mode 100644 index 0000000..c303e63 --- /dev/null +++ b/book/src/input/pointer.md @@ -0,0 +1 @@ +# Pointer diff --git a/book/src/input/text.md b/book/src/input/text.md new file mode 100644 index 0000000..bb182be --- /dev/null +++ b/book/src/input/text.md @@ -0,0 +1 @@ +# Text diff --git a/book/src/introduction.md b/book/src/introduction.md new file mode 100644 index 0000000..e10b99d --- /dev/null +++ b/book/src/introduction.md @@ -0,0 +1 @@ +# Introduction diff --git a/book/src/rendering/README.md b/book/src/rendering/README.md new file mode 100644 index 0000000..1fe7075 --- /dev/null +++ b/book/src/rendering/README.md @@ -0,0 +1 @@ +# Rendering diff --git a/book/src/rendering/canvases.md b/book/src/rendering/canvases.md new file mode 100644 index 0000000..fd575ab --- /dev/null +++ b/book/src/rendering/canvases.md @@ -0,0 +1 @@ +# Canvases diff --git a/book/src/rendering/primitives.md b/book/src/rendering/primitives.md new file mode 100644 index 0000000..564479a --- /dev/null +++ b/book/src/rendering/primitives.md @@ -0,0 +1 @@ +# Primitives diff --git a/book/src/rendering/state.md b/book/src/rendering/state.md new file mode 100644 index 0000000..5a47f4e --- /dev/null +++ b/book/src/rendering/state.md @@ -0,0 +1 @@ +# Graphics State diff --git a/book/src/rendering/tessellation.md b/book/src/rendering/tessellation.md new file mode 100644 index 0000000..c35acf4 --- /dev/null +++ b/book/src/rendering/tessellation.md @@ -0,0 +1 @@ +# Tessellation diff --git a/book/src/rendering/text.md b/book/src/rendering/text.md new file mode 100644 index 0000000..bb182be --- /dev/null +++ b/book/src/rendering/text.md @@ -0,0 +1 @@ +# Text