Introduction

Welcome to the API documentation of Giro3D.

➡️ If you are looking for an interactive tutorial, please look at the getting started page instead.

Here is a brief overview of the main concepts behind Giro3D.

Instance

The Instance is the entry point of a Giro3D context. It contains entities that represent dynamically updated objects and make the most of a Giro3D scene. Each instance is hosted by a DOM element (a <div>) that will contain the <canvas> used to render the scene.

// Get the DOM element that will contain the Giro3D instance
const div = document.getElementById('giro3d-view');

const instance = new Instance(div);
Copy

Under the hood, Giro3D uses three.js to render the scene. To directly access the three.js scene, you can use the scene property.

To add an entity to the instance, use the Instance.add() method. Note that this method should also be used to add a regular three.js Object3Ds as well.

💡 You can have multiple instances in the same web page, as long as each of them has its own canvas.

The main loop

Contrary to many video games or other interactive applications, Giro3D updates its state and renders the scene to the canvas only when notified, instead of periodically (for example 60 times per second). Many classes in Giro3D notify the instance when something has changed (mainly entities), but not all changes can be detected by Giro3D. The rationale is to save CPU and GPU cycles, as well as power on mobile devices.

💡 To manually trigger an Instance update, you can use the Instance.notifyChange() method. This is useful when the state of the scene has changed in a way that Giro3D cannot detect:

const instance = new Instance(...);

// Do something that Giro3D cannot detect, such as changing a CSS style.

// Make sure that Giro3D is notified.
instance.notifyChange();
Copy

Entities

Entities are the first-class citizens in Giro3D. Each entity manages a collection of renderable objects, and is responsible for their life cycle. The root 3D object of the entity can be accessed through the object3d accessor.

For example, the Map entity represents a 2D or 2.5D surface split into hierarchical tiles.

💡 To implement your own renderable entity, create a subclass of the Entity3D class:

class MyCustomEntity extends Entity3D {
    constructor() {
        super(id, new THREE.Group());
    }
}
Copy

The progress and loading properties

Various classes in Giro3D provide the progress and loading API. This API can be used to determine if the object is currently performing asynchronous operations.

• loading is a boolean that indicates whether the object is currently performing an asynchronous task.
• progress is a number (between zero and one) that indicates the percentage of progress of the tasks this object is performing.

💡 To help implementing this API, you can use the OperationCounter class.

Memory management

Most objects in Giro3D are automatically managed by the garbage collector, ensuring that no memory leak happens.

However, some objects, such as three.js textures, must be manually disposed. In this case, refer to the relevant documentation to determine if the object is manually managed.

💡 three.js's WebGLRenderer has an info property that returns the number of unmanaged resources in GPU memory. You can access this renderer from the Instance using the renderer property.