From 5ab5fb079ac2b48f77b007684bbad1ad48c9eb98 Mon Sep 17 00:00:00 2001 From: marceline-cramer Date: Sun, 7 Aug 2022 16:47:18 -0600 Subject: [PATCH 1/6] Add initial book --- book/.gitignore | 1 + book/book.toml | 6 ++++++ book/src/SUMMARY.md | 29 +++++++++++++++++++++++++++ book/src/credits.md | 1 + book/src/ecosystem/README.md | 1 + book/src/ecosystem/finding-scripts.md | 1 + book/src/ecosystem/fonts.md | 1 + book/src/ecosystem/localization.md | 1 + book/src/ecosystem/messages.md | 1 + book/src/ecosystem/protocols.md | 1 + book/src/glossary.md | 1 + book/src/impl-rs/backends.md | 1 + book/src/impl-rs/examples.md | 1 + book/src/impl-rs/process.md | 1 + book/src/impl-rs/usage.md | 1 + book/src/impl/README.md | 4 ++++ book/src/input/README.md | 1 + book/src/input/pointer.md | 1 + book/src/input/text.md | 1 + book/src/introduction.md | 1 + book/src/rendering/README.md | 1 + book/src/rendering/canvases.md | 1 + book/src/rendering/primitives.md | 1 + book/src/rendering/state.md | 1 + book/src/rendering/tessellation.md | 1 + book/src/rendering/text.md | 1 + 26 files changed, 62 insertions(+) create mode 100644 book/.gitignore create mode 100644 book/book.toml create mode 100644 book/src/SUMMARY.md create mode 100644 book/src/credits.md create mode 100644 book/src/ecosystem/README.md create mode 100644 book/src/ecosystem/finding-scripts.md create mode 100644 book/src/ecosystem/fonts.md create mode 100644 book/src/ecosystem/localization.md create mode 100644 book/src/ecosystem/messages.md create mode 100644 book/src/ecosystem/protocols.md create mode 100644 book/src/glossary.md create mode 100644 book/src/impl-rs/backends.md create mode 100644 book/src/impl-rs/examples.md create mode 100644 book/src/impl-rs/process.md create mode 100644 book/src/impl-rs/usage.md create mode 100644 book/src/impl/README.md create mode 100644 book/src/input/README.md create mode 100644 book/src/input/pointer.md create mode 100644 book/src/input/text.md create mode 100644 book/src/introduction.md create mode 100644 book/src/rendering/README.md create mode 100644 book/src/rendering/canvases.md create mode 100644 book/src/rendering/primitives.md create mode 100644 book/src/rendering/state.md create mode 100644 book/src/rendering/tessellation.md create mode 100644 book/src/rendering/text.md 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..6fb97a8 --- /dev/null +++ b/book/src/SUMMARY.md @@ -0,0 +1,29 @@ +# Summary + +[Introduction](introduction.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/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..d35708f --- /dev/null +++ b/book/src/impl-rs/process.md @@ -0,0 +1 @@ +# Development Process diff --git a/book/src/impl-rs/usage.md b/book/src/impl-rs/usage.md new file mode 100644 index 0000000..8f04b05 --- /dev/null +++ b/book/src/impl-rs/usage.md @@ -0,0 +1 @@ +# Usage 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 From 6f185ae34486ef28dde7d43f14988b37447c3f67 Mon Sep 17 00:00:00 2001 From: mars Date: Fri, 12 Aug 2022 17:05:46 -0600 Subject: [PATCH 2/6] Add build instructions --- book/src/impl-rs/usage.md | 97 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 96 insertions(+), 1 deletion(-) diff --git a/book/src/impl-rs/usage.md b/book/src/impl-rs/usage.md index 8f04b05..d9815eb 100644 --- a/book/src/impl-rs/usage.md +++ b/book/src/impl-rs/usage.md @@ -1 +1,96 @@ -# Usage +# 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. + +It is in active development, and is, at the moment, the singular focal point for +host-side Canary programming. Even this documentation's source code is located +in the `canary-rs` source tree. + +`canary-rs` provides a graphical "test harness" that embeds the Canary runtime +into a lightweight graphical app. It has two purposes: first of all, to give +script authors a playground independent of a larger framework to safely debug, +benchmark, and experiment with their scripts, and second of all, 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 provieded 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, that can +optionally be built and loaded into the test harness in order to ensure its +functioning. + +To build it, you must first follow the instructions above 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 very early development, and has both +an unstable API and version. It is not advised to use it in projects not +involved in its development in its current state. + +`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 either be a specific +tag, some point in the commit history, or whatever the latest commit on `main` +is. + +Tebibyte Media is 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. From ce05070a92834d408f1bb760f7650c7f1dd2a721 Mon Sep 17 00:00:00 2001 From: mars Date: Tue, 16 Aug 2022 20:07:23 -0600 Subject: [PATCH 3/6] Proofread usage page --- book/src/impl-rs/usage.md | 41 +++++++++++++++++++-------------------- 1 file changed, 20 insertions(+), 21 deletions(-) diff --git a/book/src/impl-rs/usage.md b/book/src/impl-rs/usage.md index d9815eb..7a5ac5a 100644 --- a/book/src/impl-rs/usage.md +++ b/book/src/impl-rs/usage.md @@ -4,14 +4,15 @@ implementation for Canary. It is written in Rust, and is licensed under the LGPLv3. -It is in active development, and is, at the moment, the singular focal point for -host-side Canary programming. Even this documentation's source code is located -in the `canary-rs` source tree. +`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 of all, to give +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 of all, to give Canary +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. @@ -19,7 +20,7 @@ applications. 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 provieded by `canary-rs`. +to build the example script provided by `canary-rs`. ## Building the test harness @@ -47,12 +48,11 @@ $ 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, that can -optionally be built and loaded into the test harness in order to ensure its -functioning. +`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 to clone and build the -test harness and to set up the Rust toolchain. +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: @@ -66,16 +66,16 @@ $ 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: +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 very early development, and has both -an unstable API and version. It is not advised to use it in projects not -involved in its development in its current state. +***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) @@ -87,10 +87,9 @@ 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 either be a specific -tag, some point in the commit history, or whatever the latest commit on `main` -is. +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 is 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. +[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. From 0903255edad1f27600464fa332b5bf141e7f9340 Mon Sep 17 00:00:00 2001 From: mars Date: Mon, 5 Sep 2022 00:53:05 -0600 Subject: [PATCH 4/6] Add WIP History chapter --- book/src/SUMMARY.md | 1 + book/src/history.md | 16 ++++++++++++++++ 2 files changed, 17 insertions(+) create mode 100644 book/src/history.md diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index 6fb97a8..88f08b1 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -1,6 +1,7 @@ # Summary [Introduction](introduction.md) +[History](history.md) - [Implementation](impl/README.md) - [Development Process](impl-rs/process.md) 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. From 33274f6c77db1b7a5ebb150ea9b4a29120e10ce4 Mon Sep 17 00:00:00 2001 From: mars Date: Mon, 5 Sep 2022 00:56:04 -0600 Subject: [PATCH 5/6] Add WIP Development Process feature guidelines --- book/src/impl-rs/process.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/book/src/impl-rs/process.md b/book/src/impl-rs/process.md index d35708f..2e75489 100644 --- a/book/src/impl-rs/process.md +++ b/book/src/impl-rs/process.md @@ -1 +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. From 77a99427c855d2e96239ffb2d049237650dc12ad Mon Sep 17 00:00:00 2001 From: lilithium-hydride Date: Mon, 12 Sep 2022 13:58:47 -0400 Subject: [PATCH 6/6] fix snake/kebab typo in usage --- book/src/impl-rs/usage.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/src/impl-rs/usage.md b/book/src/impl-rs/usage.md index 7a5ac5a..0120d1b 100644 --- a/book/src/impl-rs/usage.md +++ b/book/src/impl-rs/usage.md @@ -62,7 +62,7 @@ $ rustup target add wasm32-unknown-unknown Next, compile the example script: ```sh -$ cargo build --release -p sao_ui_rs --target wasm32-unknown-unknown +$ 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`.