maobo/cup_edit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update README

Browse Source
This commit is contained in:
Nick Fisher
2023-10-03 15:26:10 +11:00
parent a6e7a71998
commit 2982cf0423
1 changed files with 198 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files

230
README.md
View File

@@ -1,20 +1,204 @@
# polyvox_filament
# Flutter Filament
Cross-platform, Physically-based rendering inside Flutter applications.
Flutter plugin wrapping the Filament renderer https://github.com/google/filament.
Filament is bundled with pre-compiled static libraries:
Powers the Polyvox and odd-io engines.
iOS/MacOS: v1.43.1
(iOS release build has a skybox bug so the debug versions are currently shipped on iOS)
Windows - v1.32.4
(Waiting for https://github.com/google/filament/issues/7078 to be resolved before upgrading, not sure exactly when the bug was introduced but it was somewhere between v1.34.2 and v1.40.0)
Linux - TODO, previously was v1.24.1 but this needs to be bumped up to parity with the other platforms (ideally v.1.43.1)
# Sponsors
Thank you to odd-io for sponsoring work on supporting Windows, raycasting, testing and documentation.
# Overview
## Versioning
Last tested on Flutter `3.15.0-15.2.pre`. This is on the Flutter beta channel, so run:
```
flutter channel beta
flutter upgrade
```
||Android|iOS|MacOS|Windows|Linux|WebGL
|---|---|---|---|---|---||
|Filament|v1.43.1 (arm64/armeabi-v7a/x86/x86_64)|v1.43.1* (arm64)|v1.43.1 (arm64)|v1.32.4 (x86_64)|TODO**|TODO***|
|Flutter||3.15.0-15.2.pre|3.15.0-15.2.pre|3.15.0-15.2.pre
* iOS release build has a skybox bug so the debug versions are currently shipped on iOS
** (Waiting for https://github.com/google/filament/issues/7078 to be resolved before upgrading, not sure exactly when the bug was introduced but it was somewhere between v1.32.4 and v1.40.0)
*** Texture widget not currently supported on web in Flutter.
## Features
|Feature|Supported|
|---|---|
|glTF|Y|
|glb|Y|
# Basic Setup
## Clone flutter_filament
This plugin is not yet published to pub.dev. To use in your project, simply clone the repository and pull the latest binaries from Git LFS:
```
cd $HOME
git clone <repo> && cd flutter_filament
git lfs pull
```
You *do not need to build Filament yourself*. The repository is bundled with all necessary headers/static libraries (`windows/lib`, `ios/lib`, `macos/lib` and `linux/lib`) and the Flutter plugin has been configured to link at build time.
If you want to run the example project to check:
```
cd example && flutter run -d <macos/windows/Your iPhone/etc>
```
## Add dependency
Add the plugin as a dependency in the pubspec.yaml for your application:
```
name: your_project
description: Your project
...
dependencies:
flutter:
sdk: flutter
flutter_filament:
path: <path where you cloned the repository>
```
# Usage
See the `example` project for a complete sample of the below steps.
## Creating the viewport widget and controller
To embed a viewport in your app, create an instance of `FilamentControllerFFI` somewhere in your app:
e.g.
```
class MyApp extends StatelessWidget {
final _filamentController = FilamentControllerFFI();
...
}
```
Constructing this object only load symbols from the native FFI library.
(Note this is not (yet) a singleton, so ensure it is placed somewhere in the widget hierachy where it will not be garbage-collected until you no longer need a rendering canvas).
Next, create an instance of `FilamentWidget` in the widget hierarchy where you want the rendering canvas to appear. This can be sized as large or as small as you want. Flutter widgets can be positioned above or below the `FilamentWidget`.
```
class MyApp extends StatelessWidget {
final _filamentController = FilamentControllerFFI();
@override
Widget build(BuildContext context) {
return MaterialApp(
color: Colors.white,
home: Scaffold(backgroundColor: Colors.white, body: Stack(children:[
Container(color:Colors.green, height:100, width:100),
Positioned.fill(top:100, left:100child:FilamentWidget(controller:_filamentController)),
Positioned(right:0, bottom:0, child:Container(color:Colors.purple, height:100, width:100))
])));
}
}
```
When a `FilamentWidget` is added to the widget hierarchy:
1) on the first frame, by default a Container will be rendered with solid red. If you want to change this, pass a widget as the `initial` paramer to the `FilamentWidget` constructor.
2) on the second frame, `FilamentWidget` will retrieve its actual size and request the `FilamentController` to create:
a) the backing textures needed to insert a `Texture` widget into
b) a rendering thread
c) a `FilamentViewer` and an `AssetManager`, which will allow you to load assets/cameras/lighting/etc via the `FilamentController`
If this was successful, you should see a black screen
### Rendering
By default, the FilamentController will only render into the viewport by manually calling `render()` on the FilamentController. This is to avoid needlessly running a render loop when there is nothing to display.
If you want to render at 60fps, call `setRendering(true)` on `FilamentController`.
### Assets
To add a glTF asset to the scene, call `loadGlb()` on `FilamentController` with the Flutter asset path to your .glb file.
For example, if your `pubspec.yaml` looks like this:
```
flutter:
assets:
- assets/models/bob.glb
```
Then you would call the following
```
var entity = _filamentController.loadGlb("assets/models/bob.glb");
```
You can also pass a URI to indicate that the glTF file should be loaded from the filesystem:
```
var entity = _filamentController.loadGlb("file:///tmp/bob.glb");
```
The returned value is an integer handle that be used to manipulate the asset (better referred to as the "entity") in the scene.
E.g. to remove the asset:
```
_filamentController.removeAsset(entity);
```
### Camera movement
To enable mouse/swipe navigation through the scene, wrap the `FilamentWidget` inside a `FilamentGestureDetector`:
```
class MyApp extends StatelessWidget {
final _filamentController = FilamentControllerFFI();
@override
Widget build(BuildContext context) {
return MaterialApp(
color: Colors.white,
home: Scaffold(backgroundColor: Colors.white, body: Stack(children:[
Container(color:Colors.green, height:100, width:100),
Positioned.fill(top:100, left:100child:FilamentWidget(controller:_filamentController)),
Positioned(right:0, bottom:0, child:Container(color:Colors.purple, height:100, width:100))
])));
}
}
```
# Building Filament from source
```
git clone git@github.com:nmfisher/filament.git && cd filament
```
## Windows
To support embedding GPU textures in Flutter (rather than copying to a CPU pixel buffer on every frame), we need to build a slightly customized version of Filament that uses GLES on Windows (rather than the default, which uses OpenGL).
Separately, we also force the Filament gltfio library to load assets via in-memory buffers, rather than the filesystem. This is simply a convenience so we don't have to use different logic for gltf resource loading across platforms.
```
git checkout flutter-filament-windows
mkdir out && cd out
```
Only arm64 libs are provided for iOS/MacOS, only x64 libs are provided for Windows/Linux, all provided for Android.
Building notes:
- we remove -fno-exceptions from CMakeLists.txt
On Android/iOS, we remove -fno-exceptions from CMakeLists.txt
Project structure:
- most shared code/headers under ios/src (because I still can't get podspec to build a target with symlinks or relative paths)
@@ -28,7 +212,7 @@ e.g.
- Note also need to specifically build imageio/png/tinyexr
- if release build, then need to comment out -fno-exceptions
Linux specific
# Linux specific
(Fedora 34)
Building Filament:
@@ -37,42 +221,24 @@ env LIBRARY_PATH=/usr/lib/gcc/x86_64-redhat-linux/11/ CC=clang CXX=clang++ CXX_F
Running example project:
export PKG_CONFIG_PATH=/usr/lib/pkgconfig/:/usr/lib64/pkgconfig/ CPLUS_INCLUDE_PATH=/usr/include/gtk-3.0/:/usr/include/pango-1.0/:/usr/include/harfbuzz:/usr/include/cairo/:/usr/include/gdk-pixbuf-2.0/:/usr/include/atk-1.0/
Extract and move both lib/ and include/ to ./ios
Web:
EMCC_CFLAGS="-Wno-missing-field-initializers -Wno-deprecated-literal-operator -fPIC" ./build.sh -c -p webgl -i debug
EMCC_CFLAGS="-I/Users/nickfisher/Documents/filament/libs/utils/include -I/Users/nickfisher/Documents/filament/libs/image/include -I/Users/nickfisher/Documents/filament/libs/math/include -I../../..//third_party/basisu/encoder/ -I../../..//third_party/libpng/ -I../../..//third_party/tinyexr/ -fPIC" emmake make
# Running
## Android
## Materials
- MainActivity.kt must have the following:
```
class MainActivity: FlutterActivity() {
override fun getTransparencyMode(): TransparencyMode {
return TransparencyMode.transparent
}
}
```
and theme must have the following in `styles.xml`
```
<style name="NormalTheme" parent="@android:style/Theme.Light.NoTitleBar">
<item name="android:windowBackground">@android:color/transparent</item>
</style>
```
Remember to set the background colour for your Scaffold to transparent!
Materials
glTF assets The default
- there is a simple material (unlit/opaque) used for background images. This is created by:
```
filament/out/release/filament/bin/matc -a opengl -a metal -o materials/image.filamat materials/image.mat
filament/out/release/filament/bin/resgen -c -p image -x ios/include/material/ materials/image.filamat
```