Engine
Engine plays the role of the main controller, primarily encompassing functions such as canvas, render control, and engine subsystem management:
- Canvas: Operations related to the main canvas, such as modifying the canvas width and height.
- Render Control: Functions to control the execution, pause, resume of rendering, vertical synchronization, etc.
- Engine Subsystem Management: Scene Management, Resource Management, Physics System, Interaction System, XR System
- Execution Environment Context Management: Management of context for execution environments like WebGL.
Initialization
To facilitate users directly creating a web engine, we provide the WebGLEngine, which supports WebGL1.0 and WebGL2.0.
const engine = await WebGLEngine.create({
canvas: "canvas-id",
colorSpace: {...},
graphicDeviceOptions: {...},
gltf: {...},
ktx2Loader: {...}
});Below is a description of the configuration types passed when creating the engine:
| Configuration | Description |
|---|---|
| canvas | Can be a canvas ID (string) or a canvas object (`HTMLCanvasElement |
| graphicDeviceOptions | Configuration related to the graphics device, e.g., webGLMode can control WebGL1/2. Properties other than webGLMode will be passed to the context, more details can be found in getContext parameters explanation. |
| colorSpace | Color space, ColorSpace.Gamma or ColorSpace.Linear. |
| gltf | GLTF Loader configuration, workerCount is used to configure the number of workers for meshOpt: { meshOpt: { workerCount: number } }. |
| ktx2Loader | KTX2 Loader configuration, workerCount is used to configure the number of workers for the ktx2 decoder: { priorityFormats: Array<KTX2TargetFormat>; transcoder: KTX2Transcoder; workerCount: number }. If workerCount is greater than 0, worker threads will be created; if it equals 0, only the main thread will be used. |
For more related configuration information, please refer to Physics System, Interaction System, XR System.
Properties
| Property Name | Description |
|---|---|
| time | Engine time-related information, more details can be found in Time |
| vSyncCount | Vertical sync refresh rate. The engine defaults to enable vertical sync with a refresh rate vSyncCount of 1 (same as the screen refresh rate). If vSyncCount is set to 2, the engine updates once every 2 screen refresh frames. |
| resourceManager | Resource manager, generally used for loading and releasing assets. |
| sceneManager | Scene manager. Galacean supports rendering multiple scenes simultaneously, and the scene manager allows convenient management of scene additions, deletions, modifications, and queries. More details can be found in Scene. |
| inputManager | Interaction manager, generally used to get information about keyboards, touch, and wheel inputs. More details can be found in Interaction. |
Refresh Rate
By default, the engine uses vertical sync mode and controls the rendering refresh rate with vSyncCount. In this mode, the rendering frame waits for the screen's vertical sync signal, and vSyncCount represents the desired number of screen sync signals between rendering frames. The default value is 1, and this property must be an integer. For example, if we want to render 30 frames per second on a device with a 60Hz screen refresh rate, we can set this value to 2.
Users can also disable vertical sync by setting vSyncCount to 0 and then setting targetFrameRate to the desired frame rate. In this mode, rendering does not consider vertical sync signals. For instance, a value of 120 means 120 frames, which indicates a desired refresh rate of 120 times per second.
// Vertical sync
engine.vSyncCount = 1;
engine.vSyncCount = 2;
// No vertical sync
engine.vSyncCount = 0;
engine.targetFrameRate = 120;⚠️ Non-vertical sync is not recommended.