Ajout d’une couche WebGL personnalisée à une carte

Le kit de développement logiciel (SDK) web Azure Maps prend en charge la création de couches personnalisées à l’aide de WebGL. Basé sur OpenGL ES, WebGL permet de restituer des graphismes 2D et 3D dans les navigateurs web.

À l’aide de WebGL, vous pouvez créer des graphismes interactifs hautes performances qui s’affichent dans le navigateur en temps réel et prennent en charge des scénarios tels que les simulations, la visualisation des données, les animations et la modélisation 3D.

Les développeurs ont accès au contexte WebGL de la carte pendant le rendu. Ils utilisent des couches WebGL personnalisées dans le cadre de l’intégration à d’autres bibliothèques (par exemple three.js et deck.gl) pour fournir du contenu enrichi et interactif sur la carte.

Ajout d’une couche WebGL

Pour pouvoir ajouter une couche WebGL à une carte, vous devez disposer d’un objet qui implémente l’interface WebGLRenderer. Tout d’abord, créez une couche WebGL en fournissant un id et un objet renderer au constructeur, puis ajoutez-la à la carte pour permettre la restitution de celle-ci.

L’exemple de code suivant montre comment ajouter une couche WebGL à une carte :

var myRenderer = {
    /**
     * Either "2d" or "3d". Defaults to "2d".
     * - "3d" to use the depth buffer and share it with other layers
     * - "2d" to add a layer with no depth. If you need to use the depth buffer for a "2d"
     *   layer you must use an offscreen framebuffer and the prerender method.
     */
    renderingMode: "2d",

    /**
     * Optional method called when the layer has been added to the Map.
     * This gives the layer a chance to initialize gl resources and register event listeners.
     * @param map The Map this custom layer was just added to.
     * @param gl The gl context for the map.
     */
    onAdd: function (map, gl) {},

    /**
     * Optional method called when the layer has been removed from the Map.
     * This gives the layer a chance to clean up gl resources and event listeners.
     * @param map The Map this custom layer was just added to.
     * @param gl The gl context for the map.
     */
    onRemove: function (map, gl) {},

    /**
     * Optional method called during a render frame to allow a layer to prepare resources
     * or render into a texture.
     *
     * The layer cannot make any assumptions about the current GL state and must bind a framebuffer before rendering.
     *
     * @param gl The map's gl context.
     * @param matrix The map's camera matrix.
     */
    prerender: function (gl, matrix) {},

    /**
     * Required. Called during a render frame allowing the layer to draw into the GL context.
     *
     * The layer can assume blending and depth state is set to allow the layer to
     * properly blend and clip other layers. The layer cannot make any other 
     * assumptions about the current GL state.
     *
     * If the layer needs to render to a texture, it should implement the prerender
     * method to do this and only use the render method for drawing directly into the
     * main framebuffer.
     *
     * The blend function is set to gl.blendFunc(gl.ONE, gl.ONE_MINUS_SRC_ALPHA).
     * This expects colors to be provided in premultiplied alpha form where the r, g and b
     * values are already multiplied by the a value. If you are unable to provide colors in
     * premultiplied form you may want to change the blend function to
     * gl.blendFuncSeparate(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA, gl.ONE, gl.ONE_MINUS_SRC_ALPHA).
     *
     * @param gl The map's gl context.
     * @param matrix The map's camera matrix.
     */
    render: function (gl, matrix) {}
};
 
//Add the layer to the map.
map.layers.add(new atlas.layer.WebGLLayer("layerId", { renderer: myRenderer }));

Notes

La classe WebGLLayer prend en charge les options de couche minZoom, maxZoom et visible.

//Add the layer to the map with layer options. 
map.layers.add(new atlas.layer.WebGLLayer("layerId", 
    { 
        renderer: myRenderer, 
        minZoom: 10, 
        maxZoom: 22, 
        visible: true
    }
));

Cet exemple affiche un triangle sur la carte à l’aide d’une couche WebGL.

A screenshot showing a triangle rendered on a map, using a WebGL layer.

Pour obtenir un exemple entièrement fonctionnel avec du code source, consultez Couche WebGL 2D simple dans les exemples Azure Maps.

La matrice de caméra de la carte est utilisée pour projeter le point Mercator sphérique en coordonnées gl. Le point Mercator [0, 0] représente le coin supérieur gauche du monde Mercator, et [1, 1] le coin inférieur droit. Lorsque la valeur renderingMode est définie sur "3d", la coordonnée z est conforme. Une boîte dont les longueurs x, y et z sont identiques en unités Mercator s’affiche sous forme de cube.

La classe MercatorPoint possède des méthodes statiques fromPosition, fromPositions et toFloat32Array qui permettent de convertir une position géospatiale en point Mercator. De même, les méthodes toPosition et toPositions peuvent être utilisées pour projeter un point Mercator en position.

Afficher un modèle 3D

Utilisez une couche WebGL pour afficher des modèles 3D. L’exemple suivant montre comment charger un fichier glTF et le restituer sur la carte à l’aide de three.js.

Vous devez ajouter les fichiers de script suivants.

<script src="https://unpkg.com/three@latest/build/three.min.js"></script>
<script src="https://unpkg.com/three@latest/examples/js/loaders/GLTFLoader.js"></script>

Cet exemple affiche un perroquet 3D animé sur la carte.

A screenshot showing an animated 3D parrot on the map.

Pour obtenir un exemple entièrement fonctionnel avec du code source, consultez Couche WebGL personnalisée Three dans les exemples Azure Maps.

La fonction onAdd charge un fichier .glb en mémoire et instancie des objets three.js (caméra, scène, lumière, etc.) et un THREE.WebGLRenderer.

La fonction render calcule la matrice de projection de la caméra et affiche le modèle sur la scène.

Conseil

  • Pour obtenir une animation continue et fluide, vous pouvez redessiner une image unique en appelant map.triggerRepaint() dans la fonction render.
  • Pour activer l’anticrénelage, il vous suffit de définir antialias sur true parmi les options de style lors de la création de la carte.

Afficher un modèle 3D à l’aide de babylon.js

Babylon.js est l’un des principaux moteurs graphiques WebGL du monde. L’exemple suivant montre comment charger un fichier GLTF et le restituer sur la carte à l’aide de babylon.js.

Vous devez ajouter les fichiers de script suivants.

<script src="https://cdn.babylonjs.com/babylon.js"></script> 
<script src="https://cdn.babylonjs.com/loaders/babylonjs.loaders.min.js"></script>

Cet exemple restitue une tour satellite sur la carte.

La fonction onAdd instancie un moteur BABYLON et une scène. Il charge ensuite un fichier .gltf à l’aide de BABYLON.SceneLoader.

La fonction render calcule la matrice de projection de la caméra et affiche le modèle sur la scène.

A screenshot showing an example of rendering a 3D model using babylon.js.

Pour obtenir un exemple entièrement fonctionnel avec du code source, consultez Couche WebGL personnalisée Babylon dans les exemples Azure Maps.

Affichage d’une couche deck.gl

Une couche WebGL peut être utilisée pour afficher des couches à partir de la bibliothèque deck.gl. L’exemple suivant illustre la visualisation des données du flux de migration des personnes aux États-Unis, d’un comté à l’autre, sur un certain intervalle de temps.

Vous devez ajouter le fichier de script suivant.

<script src="https://unpkg.com/deck.gl@latest/dist.min.js"></script>

Définissez une classe de couche qui étend atlas.layer.WebGLLayer.

class DeckGLLayer extends atlas.layer.WebGLLayer { 

    constructor(options) { 
        super(options.id); 

        //Create an instance of deck.gl layer 
        this._mbLayer = new deck.MapboxLayer(options); 

        //Create a renderer 
        const deckGLRenderer = { 
            renderingMode: "3d", 
            onAdd: (map, gl) => { 
               this._mbLayer.onAdd?.(map["map"], gl); 
            }, 
            onRemove: (map, gl) => { 
                this._mbLayer.onRemove?.(map["map"], gl); 
            }, 
            prerender: (gl, matrix) => { 
                this._mbLayer.prerender?.(gl, matrix); 
            }, 
            render: (gl, matrix) => { 
                this._mbLayer.render(gl, matrix); 
            } 
        }; 
        this.setOptions({ renderer: deckGLRenderer }); 
    } 
}

Cet exemple affiche une couche arc-layer de la bibliothèque deck.gl.

A screenshot showing an arc-layer from the Deck G L library.

Pour obtenir un exemple entièrement fonctionnel avec du code source, consultez Couche WebGL personnalisée Deck GL dans les exemples Azure Maps.

Étapes suivantes

En savoir plus sur les classes et les méthodes utilisées dans cet article :

WebGLLayer

WebGLLayerOptions

Interface WebGLRenderer

MercatorPoint

  • Last updated on