From 03f8e2e35380337f77bd6581a7687e6a42bd2925 Mon Sep 17 00:00:00 2001 From: Nick Fisher Date: Thu, 27 Jun 2024 21:46:06 +0800 Subject: [PATCH] docs: update docs --- docs.json | 2 +- docs/contributing.mdx | 6 +++--- docs/index.mdx | 39 +++++++++++++++++++++++++++++++++++++-- docs/quickstart.mdx | 2 +- 4 files changed, 42 insertions(+), 7 deletions(-) diff --git a/docs.json b/docs.json index 9708aca6..0f3cd3a2 100644 --- a/docs.json +++ b/docs.json @@ -12,7 +12,7 @@ ], ["Misc.", [ ["Playground", "https://dartpad.thermion.dev"], - ["Examples", "https://dartpad.thermion.dev"], + ["Examples", "/examples"], ["Windows", "/windows"], ["Android", "/android"], ["Contributing", "/contributing"] diff --git a/docs/contributing.mdx b/docs/contributing.mdx index 3f3758f3..2456824a 100644 --- a/docs/contributing.mdx +++ b/docs/contributing.mdx @@ -1,10 +1,10 @@ ## Contributing -Thermion is an open source project and we welcome all contributions from every level of experience. +Thermion is an open source project and all contributions are welcome, no matter the level of experience. Please [join us on Discord](https://discord.gg/h2VdDK3EAQ) if you'd like some guidance or just want to chat. -## +Note that the Thermion project uses [Melos](https://melos.invertase.dev/) to manage the repository. -We are now using [Melos](https://melos.invertase.dev/) to manage the repository. This lets us auto-generate changelogs & versioning from commit messages, so if you wish to submit a PR, please use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/). +This lets us auto-generate changelogs & versioning from commit messages, so if you wish to submit a PR, please use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/). diff --git a/docs/index.mdx b/docs/index.mdx index b119fc1f..2d82d1b1 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -4,6 +4,10 @@ Thermion is a framework for creating cross-platform 3D applications with Dart an ## Overview +Below is a general overview of how the Thermion packages are structured to ensure a clean separation between the general Dart components, and the Flutter specific components. + +If you want a more detailed explanation of how to start rendering 3D content inside a Flutter app, [click here to view the quickstart page](/quickstart). + ### Package structure  Thermion is divided into two packages: @@ -18,8 +22,39 @@ For example, Thermion ships with examples for rendering with Dart only (no Flutt ### ThermionViewer (`thermion_dart`) -// TODO +The ThermionViewer class provides an API for creating and interacting with 3D scenes powered by the Filament rendering engine. + +It allows loading 3D models in glTF format, adding lights and a skybox, manipulating the camera, animating objects, and more. + +Key functionalities include: +- Scene Management: Load and manipulate entities, lights, skyboxes, and background elements within a 3D scene. +- Rendering Control: Manage rendering loop, frame rate, and post-processing effects like tone mapping and bloom. +- Camera Control: Position and orient the camera, adjust focal length, and control exposure settings. +- Animation: Play, pause, and manipulate skeletal and morph target animations. +- Entity Manipulation: Transform entities (position, rotation, scale), set material properties, and manage parent-child relationships. +- Collision Detection (experimental): Add collision components to entities and test for collisions within the scene. +- Input Handling: Interact with the scene using touch gestures for panning, rotating, and zooming. +- Developers use the ThermionViewer class to build and control the behavior of their 3D applications. + +### ThermionFlutterPlugin + +The ThermionFlutterPlugin class handles the platform-specific initialization required to embed a Filament rendering surface within a Flutter Widget. + +This includes creating a texture and managing the application lifecycle to pause rendering when the app is inactive. + +You will generally only need to interact with `ThermionFlutterPlugin` directly to create or dispose of a ThermionViewer. ### ThermionWidget (`thermion_flutter`) -// TODO +`ThermionWidget` is a Flutter widget that displays the 3D content rendered by a ThermionViewer. + +It handles creating and managing the underlying platform-specific texture that Filament renders to, and provides a way to embed this texture within the Flutter widget tree. + +Key features of ThermionWidget include: +- Texture Management: It creates, resizes, and destroys the ThermionFlutterTexture used to display the rendered content from the ThermionViewer. +- Platform Adaption: It handles platform-specific differences, such as texture coordinate systems, to ensure consistent rendering across different platforms. +- Initialization Handling: Displays a placeholder (configurable via the initial property) while the Filament texture is being initialized, providing a smoother user experience. +- Seamless Integration: Integrates seamlessly within the Flutter widget tree, allowing developers to combine 2D and 3D content easily. +- Resize Handling: It listens for resize events and automatically resizes the underlying texture to match, ensuring the 3D content scales correctly. + + diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx index ee1c0707..5fbc62b1 100644 --- a/docs/quickstart.mdx +++ b/docs/quickstart.mdx @@ -1,6 +1,6 @@ ## Quickstart (Flutter) -> You can find the entire project below in the [https://github.com/nmfisher/thermion_examples/tree/master/flutter/quickstart](flutter/quickstart) folder of the `thermion_examples` repository. +> You can find the entire project below in the [flutter/quickstart](https://github.com/nmfisher/thermion_examples/tree/master/flutter/quickstart) folder of the `thermion_examples` repository. 1. Switch to Flutter master channel, upgrade Flutter, create a new project, then add `thermion_flutter` as a dependency