From 118b665cd3bb12b9a46aa90b73cb99f790ebb732 Mon Sep 17 00:00:00 2001 From: "dunfan.lu" Date: Sun, 29 Aug 2021 01:05:30 -0400 Subject: [PATCH 1/3] wip --- docs/lang/articles/misc/ggui.md | 158 ++++++++++++++++++++++++++++++++ 1 file changed, 158 insertions(+) create mode 100644 docs/lang/articles/misc/ggui.md diff --git a/docs/lang/articles/misc/ggui.md b/docs/lang/articles/misc/ggui.md new file mode 100644 index 0000000000000..5fd6f39f50a84 --- /dev/null +++ b/docs/lang/articles/misc/ggui.md @@ -0,0 +1,158 @@ +--- +sidebar_position: 1 + +--- + +# New UI system + +A new UI system is to be added to Taichi. The new GUI system will use GPU for rendering, which will enable it to be much faster and to render 3d scenes (for this reason, this new system is somtimes referred to as GGUI). This doc describes the APIs proveded. + +## Creating a window + +`ti.ui.Window(name, res)` creates a window. + +```python +window = ti.ui.Window('Window Title', (640, 360)) +``` + +There're three types of objects that can be displayed on a `ti.ui.Window`: + +* 2D Canvas, which can be used to draw simple 2D geometries such as circles, triangles, etc. +* 3D Scene, which can be used to render 3D meshes and particles, with a configurable camera and light sources. +* Immediate mode GUI components, buttons, textboxes, etc. + +## 2D Canvas + +### Creating a canvas + +```python +canvas = window.get_canvas() +``` +this retrieves a `Canvas` object that covers the entire window. + +### Drawing on the canvas + +```python +canvas.set_back_ground_color(...) +canvas.triangles(...) +canvas.circles(...) +canvas.lines(...) +canvas.set_image(...) +``` + +To see examples of how + +The positions/centers of geometries will be represented as floats between 0 and 1, which indicate relative positions on the canvas. + + + +## 3D Scene + +### Creating a scene +```python +scene = ti.ui.Scene() +``` +### Configuring camera +```python +camera = ti.ui.make_camera() +camera.lookat(pos) +camera.up(dir) +camera.center(pos) +camera.projection_mode(mode) +scene.set_camera(camera) +``` +where `mode` is either `ti.ui.Scene.PROJECTION_PERSPECTIVE` or `ti.ui.Scene.PROJECTION_ORTHOGONAL` + + +### Configuring light sources +#### adding a light source +```python +scene.point_light(pos,color) +``` + + +### 3d Geometries +```python +scene.mesh(vertices,indices,color) +scene.particles(positions,radius,color) +``` + + +### Rendering the scene +a scene is rendered by first rendering it on a canvas. +```python +canvas.render(scene) +``` + +## GUI components + +The support for GUI components will closely follow Dear IMGUI (and will likely be implemented using it..). + +```python +window.GUI.begin(name,x,y,width,height) +window.GUI.text(...) +window.GUI.button(...) +window.GUI.end() +``` + + +## Clearing and showing a window +```python +... +window.show() +``` + + +## Events Processing +To obtain the events that have occurred since the previous poll: + +```python +events = window.get_events() +``` + +Each `event` in `events` is an instance of `ti.ui.Event`. It has the following properties: +* `event.action`, which could be `ti.ui.ACTION_PRESSED`, `ti.ui.ACTION_RELEASED`, ... +* `event.key`, which is `ti.ui.KEY_XXXX` + +To obtain mouse position: +* `window.get_mouse_position()` + + +## Example Application + +```python +import taichi as ti + +window = ti.ui.Window("Amazing Window",res) +canvas = window.get_canvas() +scene = ti.ui.Scene() + + +while window.running: + events = window.get_event() + if ev.action == ti.ui.ACTION_PRESSED and ev.key == ti.ui.KEY_SHIFT: + ... + + canvas.clear(...) + canvas.triangles(...) + + scene.clear() + camera = ti.ui.make_camera() + camera.lookat(pos) + camera.up(dir) + camera.center(pos) + camera.projection_mode(mode) + scene.set_camera(camera) + scene.point_light(pos,color) + scene.mesh(...) + canvas.render(scene) + + window.GUI.begin(name,x,y,width,height) + window.GUI.text(...) + window.GUI.button(...) + window.GUI.end() + + window.show() + + +``` \ No newline at end of file From 7367d24f1d7766bf80bf1372c15f0e22220fe7dc Mon Sep 17 00:00:00 2001 From: unknown Date: Sun, 29 Aug 2021 23:51:03 +0800 Subject: [PATCH 2/3] init doc --- docs/lang/articles/misc/ggui.md | 98 ++++++++++++--------------------- 1 file changed, 35 insertions(+), 63 deletions(-) diff --git a/docs/lang/articles/misc/ggui.md b/docs/lang/articles/misc/ggui.md index 5fd6f39f50a84..c6a5c8c6bc560 100644 --- a/docs/lang/articles/misc/ggui.md +++ b/docs/lang/articles/misc/ggui.md @@ -3,9 +3,11 @@ sidebar_position: 1 --- -# New UI system +# A New UI system: GGUI -A new UI system is to be added to Taichi. The new GUI system will use GPU for rendering, which will enable it to be much faster and to render 3d scenes (for this reason, this new system is somtimes referred to as GGUI). This doc describes the APIs proveded. +A new UI system is to be added to Taichi. The new GUI system will use GPU for rendering, which will enable it to be much faster and to render 3d scenes. For this reason, this new system is sometimes referred to as GGUI. This doc describes the APIs provided. + +Apart from this doc, a good way of getting familiarized with GGUI is to look at the examples. Please checkout the example code provided in `examples/ggui_examples`. ## Creating a window @@ -33,17 +35,18 @@ this retrieves a `Canvas` object that covers the entire window. ### Drawing on the canvas ```python -canvas.set_back_ground_color(...) -canvas.triangles(...) -canvas.circles(...) -canvas.lines(...) -canvas.set_image(...) +canvas.set_back_ground_color(color) +canvas.triangles(vertices,color,indices,per_vertex_color) +canvas.circles(vertices,radius,color,per_vertex_color) +canvas.lines(vertices,width,indices,color,per_vertex_color) +canvas.set_image(image) ``` -To see examples of how +The arguments `vertices`, `indices`, `per_vertex_color`, `image` are all expected to be `taichi` fields. If `per_vertex_color` is provided, `color` will be ignored. -The positions/centers of geometries will be represented as floats between 0 and 1, which indicate relative positions on the canvas. +The positions/centers of geometries will be represented as floats between 0 and 1, which indicate relative positions on the canvas. For `circles` and `lines`, the `radius` and `width` argument is relative to the height of the window. +The canvas is cleared after every frame. You should call these methods within the render loop. ## 3D Scene @@ -55,33 +58,37 @@ scene = ti.ui.Scene() ### Configuring camera ```python camera = ti.ui.make_camera() +camera.position(pos) camera.lookat(pos) camera.up(dir) -camera.center(pos) camera.projection_mode(mode) scene.set_camera(camera) ``` -where `mode` is either `ti.ui.Scene.PROJECTION_PERSPECTIVE` or `ti.ui.Scene.PROJECTION_ORTHOGONAL` ### Configuring light sources -#### adding a light source +#### adding a point light ```python scene.point_light(pos,color) ``` +Note that, `point_light` needs to be called every frame. Similar to the `canvas` methods, you should call this within your render loop. ### 3d Geometries ```python -scene.mesh(vertices,indices,color) -scene.particles(positions,radius,color) +scene.mesh(vertices,indices,normals,color,per_vertex_color) +scene.particles(vertices,radius,color,per_vertex_color) ``` +Again, the arguments `vertices`, `indices`, `per_vertex_color`, `image` are all expected to be `taichi` fields. If `per_vertex_color` is provided, `color` will be ignored. + +The positions/centers of geometries should be in world-space coordinates. + ### Rendering the scene -a scene is rendered by first rendering it on a canvas. +A scene can be rendered on a canvas. ```python -canvas.render(scene) +canvas.scene(scene) ``` ## GUI components @@ -90,20 +97,22 @@ The support for GUI components will closely follow Dear IMGUI (and will likely b ```python window.GUI.begin(name,x,y,width,height) -window.GUI.text(...) -window.GUI.button(...) +window.GUI.text(text) +is_clicked = window.GUI.button(name) +new_value = window.GUI.slider_float(name,old_value,min_value,max_value) +new_color = window.GUI.slider_float(name,old_color) window.GUI.end() ``` -## Clearing and showing a window +## Showing a window ```python ... window.show() ``` +Call this method at the very end of the frame - -## Events Processing +## User Input Processing To obtain the events that have occurred since the previous poll: ```python @@ -111,48 +120,11 @@ events = window.get_events() ``` Each `event` in `events` is an instance of `ti.ui.Event`. It has the following properties: -* `event.action`, which could be `ti.ui.ACTION_PRESSED`, `ti.ui.ACTION_RELEASED`, ... -* `event.key`, which is `ti.ui.KEY_XXXX` +* `event.action`, which could be `ti.ui.PRESS`, `ti.ui.RELEASE`, ... +* `event.key`, which indicates the key related to this event To obtain mouse position: -* `window.get_mouse_position()` - +* `window.get_cursor_pos()` -## Example Application - -```python -import taichi as ti - -window = ti.ui.Window("Amazing Window",res) -canvas = window.get_canvas() -scene = ti.ui.Scene() - - -while window.running: - events = window.get_event() - if ev.action == ti.ui.ACTION_PRESSED and ev.key == ti.ui.KEY_SHIFT: - ... - - canvas.clear(...) - canvas.triangles(...) - - scene.clear() - camera = ti.ui.make_camera() - camera.lookat(pos) - camera.up(dir) - camera.center(pos) - camera.projection_mode(mode) - scene.set_camera(camera) - scene.point_light(pos,color) - scene.mesh(...) - canvas.render(scene) - - window.GUI.begin(name,x,y,width,height) - window.GUI.text(...) - window.GUI.button(...) - window.GUI.end() - - window.show() - - -``` \ No newline at end of file +To check if a specific key is currently pressed: +* `window.is_pressed(key)` From 163368bbc5f7d407f18973491c48dc85d869f17f Mon Sep 17 00:00:00 2001 From: "dunfan.lu" Date: Sun, 29 Aug 2021 12:12:03 -0400 Subject: [PATCH 3/3] format --- docs/lang/articles/misc/ggui.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/lang/articles/misc/ggui.md b/docs/lang/articles/misc/ggui.md index c6a5c8c6bc560..57903df018223 100644 --- a/docs/lang/articles/misc/ggui.md +++ b/docs/lang/articles/misc/ggui.md @@ -5,13 +5,13 @@ sidebar_position: 1 # A New UI system: GGUI -A new UI system is to be added to Taichi. The new GUI system will use GPU for rendering, which will enable it to be much faster and to render 3d scenes. For this reason, this new system is sometimes referred to as GGUI. This doc describes the APIs provided. +A new UI system is to be added to Taichi. The new GUI system will use GPU for rendering, which will enable it to be much faster and to render 3d scenes. For this reason, this new system is sometimes referred to as GGUI. This doc describes the APIs provided. Apart from this doc, a good way of getting familiarized with GGUI is to look at the examples. Please checkout the example code provided in `examples/ggui_examples`. ## Creating a window -`ti.ui.Window(name, res)` creates a window. +`ti.ui.Window(name, res)` creates a window. ```python window = ti.ui.Window('Window Title', (640, 360)) @@ -69,7 +69,7 @@ scene.set_camera(camera) ### Configuring light sources #### adding a point light ```python -scene.point_light(pos,color) +scene.point_light(pos,color) ``` Note that, `point_light` needs to be called every frame. Similar to the `canvas` methods, you should call this within your render loop. @@ -80,13 +80,13 @@ scene.mesh(vertices,indices,normals,color,per_vertex_color) scene.particles(vertices,radius,color,per_vertex_color) ``` -Again, the arguments `vertices`, `indices`, `per_vertex_color`, `image` are all expected to be `taichi` fields. If `per_vertex_color` is provided, `color` will be ignored. +Again, the arguments `vertices`, `indices`, `per_vertex_color`, `image` are all expected to be `taichi` fields. If `per_vertex_color` is provided, `color` will be ignored. The positions/centers of geometries should be in world-space coordinates. -### Rendering the scene -A scene can be rendered on a canvas. +### Rendering the scene +A scene can be rendered on a canvas. ```python canvas.scene(scene) ```