Add README.md (#8485)
This commit is contained in:
Doris Wu
GitHub
169
libs/fgviewer/README.md
Normal file
169
libs/fgviewer/README.md
Normal file
@@ -0,0 +1,169 @@
|
||||
# fgviewer
|
||||
|
||||
1. [Capabilities](#capabilities)
|
||||
2. [Setup for Desktop](#setup-for-desktop)
|
||||
3. [Setup for Android](#setup-for-android)
|
||||
4. [Debugger Usage](#debugger-usage)
|
||||
5. [Architecture Overview](#architecture-overview)
|
||||
6. [C++ Server](#c-server)
|
||||
7. [JavaScript Client](#javascript-client)
|
||||
8. [HTTP Requests](#http-requests)
|
||||
9. [Wish List](#wish-list)
|
||||
|
||||
## Capabilities
|
||||
|
||||
fgviewer is a library and web application for real-time visualization of the frame graph in Filament.
|
||||
It displays active passes and resource usage, providing insights into the rendering pipeline.
|
||||
|
||||
## Setup for Desktop
|
||||
|
||||
When using the easy build script, include the `-t` argument. For example:
|
||||
|
||||
./build.sh -ft debug gltf_viewer
|
||||
|
||||
The `t` enables a CMake option called `FILAMENT_ENABLE_FGVIEWER` and the `f` ensures that CMake gets
|
||||
re-run so that the option is honored.
|
||||
|
||||
Next, set an environment variable as follows. In Windows, use `set` instead of `export`.
|
||||
|
||||
export FILAMENT_FGVIEWER_PORT=8050
|
||||
|
||||
Next, launch any app that links against a debug build of a Filament and point your web browser to
|
||||
http://localhost:8050. Skip ahead to **Debugger Usage**.
|
||||
|
||||
## Setup for Android
|
||||
|
||||
Rebuild Filament for Android after enabling a CMake option called `FILAMENT_ENABLE_FGVIEWER`. Note that
|
||||
CMake is invoked from several places for Android (both gradle and our easy build script), so one
|
||||
pragmatic and reliable way of doing this is to simply hack `CMakeLists.txt` and
|
||||
`filament-android/CMakeLists.txt` by unconditionally setting `FILAMENT_ENABLE_FGVIEWER` to `ON`.
|
||||
|
||||
After rebuilding Filament with the option enabled, ensure that internet permissions are enabled in
|
||||
your app by adding the following into your manifest as a child of the `<manifest>` element.
|
||||
|
||||
<uses-permission android:name="android.permission.INTERNET" />
|
||||
|
||||
Now launch your app as usual. The Filament Engine sets up a server that is hardcoded to listen to
|
||||
port `8085`. Next, you will need to forward your device's TCP port `8085` to your host port of choice.
|
||||
For example, to forward the fgviewer server on your device to port `8085` on your host machine, do the
|
||||
following:
|
||||
|
||||
adb forward tcp:8085 tcp:8085
|
||||
|
||||
This lets you go to http://localhost:8085 in Chrome on your host machine.
|
||||
|
||||
## Debugger Usage
|
||||
|
||||
After opening the fgviewer page in your browser, you can see the active views are on the left panel.
|
||||
Then you can select any of them to see the active passes and resources for that view.
|
||||
|
||||
<p align="center">
|
||||
<img width="600px" src=https://github.com/user-attachments/assets/2d31767f-fc25-4f17-8c14-528fe5c6b698>
|
||||
</p>
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
<p align="center">
|
||||
<img width="450" src=https://github.com/user-attachments/assets/537ebb89-6ad0-4b93-bbeb-207d4fe9ec5a>
|
||||
</p>
|
||||
|
||||
The fgviewer library has two parts: a C++ server and a JavaScript client. The C++ server is
|
||||
responsible for instancing a [civetweb][1] context that handles HTTP requests. The
|
||||
JavaScript client is a small web app that contains a view into an in-browser database of framegraphs.
|
||||
|
||||
When a new connection is established, the client asks the server for a list of framegraphs
|
||||
in order to populate its in-browser database. If the connection is lost (e.g. if the app crashes),
|
||||
then the database stays intact and the web app is still functional.
|
||||
|
||||
## C++ Server
|
||||
|
||||
The civetweb server is wrapped by our `DebugServer` class, which provides a public interface consisting of
|
||||
a few methods invoked by the Filament engine.
|
||||
|
||||
Since each view corresponds to a frame graph, the engine should notify `DebugServer` of any changes to the views
|
||||
on the engine side.
|
||||
|
||||
- **createView** Notifies the debugger that a new view has been created.
|
||||
- **updateView** Notifies the debugger of updates to an existing view.
|
||||
- **destroyView** Notifies the debugger that a view is being removed.
|
||||
|
||||
## JavaScript Client
|
||||
|
||||
The web app is built using LitElement, a lightweight library for creating Web Components. Our goal is to keep the code simple and modern, avoiding frameworks like React or Angular.
|
||||
|
||||
The app presents a view over a pseudo-database, which is essentially a global variable holding a dictionary that maps frame graph ids to objects following the JSON structure described below.
|
||||
|
||||
## HTTP requests
|
||||
|
||||
The server responds to the following GET requests by returning a JSON blob. The `{id}` in these
|
||||
requests is a concept specific to fgviewer (not Filament) which is an 8-digit hex string for identifying frame graphs.
|
||||
|
||||
---
|
||||
|
||||
`/api/framegraphs`
|
||||
|
||||
Returns an array containing all framegraphs in an app. Example:
|
||||
|
||||
```json
|
||||
[{
|
||||
"fgid": "00000000",
|
||||
"viewName": "Main View",
|
||||
"passes": [{
|
||||
"name": "shadow pass",
|
||||
"reads": [],
|
||||
"writes": ["0"]
|
||||
}],
|
||||
"resources": [{
|
||||
"id": "0",
|
||||
"name": "shadowmap",
|
||||
"properties": [{"resolution": "256x256"}, {"is_subresource": "false"}]
|
||||
}]
|
||||
},
|
||||
{
|
||||
"fgid": "00000001",
|
||||
"viewName": "UI view",
|
||||
...
|
||||
}]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
`/api/framegraph?fg={id}`
|
||||
|
||||
Returns a specific framegraph info. Example:
|
||||
|
||||
```json
|
||||
{
|
||||
"fgid": "00000000",
|
||||
"viewName": "Main View",
|
||||
"passes": [{
|
||||
"name": "shadow pass",
|
||||
"reads": [],
|
||||
"writes": ["0"]
|
||||
}],
|
||||
"resources": [{
|
||||
"id": "0",
|
||||
"name": "shadowmap",
|
||||
"properties": [{"resolution": "256x256"}, {"is_subresource": "false"}]
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
`/api/status`
|
||||
|
||||
Returns one of the below:
|
||||
- `0`: first time connected
|
||||
- `1`: no-op
|
||||
- `{fgid}`: the corresponding frame graph has an update
|
||||
- Then the web view can request for the actual info using the previous api
|
||||
|
||||
If the request gets timeout, the web page show disconnected to the user.
|
||||
|
||||
---
|
||||
|
||||
## Wish List
|
||||
- Display the texture contents on the webview
|
||||
|
||||
[1]: https://github.com/civetweb/civetweb
|
||||
Reference in New Issue
Block a user