Adicionar uma camada WebGL personalizada a um mapa

O SDK da Web do Azure Mapas dá suporte à criação de camadas personalizadas usando WebGL. O WebGL é baseado no OpenGL ES e habilita a renderização de elementos gráficos 2D e 3D em navegadores da Web.

Usando o WebGL, você pode criar gráficos interativos de alto desempenho que são renderizados no navegador em tempo real e dão suporte a cenários como simulações, visualização de dados, animações e modelagem 3D.

Os desenvolvedores podem acessar o contexto WebGL do mapa durante a renderização e usar camadas WebGL personalizadas para integrar com outras bibliotecas, como three.js e deck.gl, para fornecer conteúdo aprimorado e interativo no mapa.

Adicionar uma camada WebGL

Antes de adicionar uma camada WebGL a um mapa, você precisa ter um objeto que implemente a interface WebGLRenderer. Primeiro, crie uma camada WebGL fornecendo um objeto id e um objeto renderer ao construtor e, em seguida, adicione a camada ao mapa para renderizá-la.

O código de exemplo a seguir demonstra como adicionar uma camada WebGL a um mapa:

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 }));

Observação

A classe WebGLLayer dá suporte às opções de camada minZoom, maxZoom e 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
    }
));

Este exemplo renderiza um triângulo no mapa usando uma camada WebGL.

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

Para obter um exemplo totalmente funcional com código-fonte, confira a camada 2D simples do WebGL nos exemplos do Azure Mapas.

A matriz da câmera do mapa é usada para projetar pontos esféricos do Mercator para coordenadas de gl. O ponto de Mercator [0, 0] representa o canto superior esquerdo do mundo Mercator, e [1, 1] representa o canto inferior direito. Quando o renderingMode for "3d", a coordenada z estará em conformidade. Uma caixa com comprimentos x, y e z idênticos em unidades Mercator seria renderizada como um cubo.

A classe MercatorPoint tem métodos estáticos fromPosition, fromPositions e toFloat32Array que podem ser usados para converter uma posição geoespacial em um ponto de Mercator. Da mesma forma, os métodos toPosition e toPositions podem ser usados para projetar um ponto de Mercator em uma Posição.

Renderizar um modelo 3D

Use uma camada WebGL para renderizar modelos 3D. O exemplo a seguir mostra como carregar um arquivo glTF e renderizá-lo no mapa usando three.js.

Você precisa adicionar os seguintes arquivos de script.

<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>

Este exemplo renderiza um papagaio 3D animado no mapa.

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

Para obter um exemplo totalmente funcional com código-fonte, confira a camada personalizada do WebGL do Three nos exemplos do Azure Mapas.

A função onAdd carrega um arquivo .glb na memória e instancia objetos three.js como Câmera, Cena, Luz e um THREE.WebGLRenderer.

A função render calcula a matriz de projeção da câmera e renderiza o modelo na cena.

Dica

  • Para ter uma animação contínua e suave, você pode disparar o redesenho de um único quadro chamando map.triggerRepaint() na função render.
  • Para habilitar o anti-aliasing, basta definir antialias como true como uma das opções de estilo ao criar o mapa.

Renderizar um modelo 3D usando o babylon.js

O Babylon.js é um dos principais mecanismos gráficos baseados no WebGL do mundo. O exemplo a seguir mostra como carregar um arquivo GLTF e renderizá-lo no mapa usando o babylon.js.

Você precisa adicionar os seguintes arquivos de script.

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

Este exemplo renderiza uma torre satélite no mapa.

A função onAdd cria uma instância de um mecanismo BABYLON e uma cena. Depois, ela carrega um arquivo .gltf usando o BABYLON.SceneLoader.

A função render calcula a matriz de projeção da câmera e renderiza o modelo na cena.

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

Para obter um exemplo totalmente funcional com código-fonte, confira a camada personalizada do Babylon do WebGL nos exemplos do Azure Mapas.

Renderizar uma camada deck.gl

Uma camada WebGL pode ser usada para renderizar camadas da biblioteca deck.gl. O exemplo a seguir demonstra a visualização de dados do fluxo de migração de pessoas nos Estados Unidos de condado para condado dentro de um determinado intervalo de tempo.

Você precisa adicionar o seguinte arquivo de script.

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

Defina uma classe de camada que estende 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 }); 
    } 
} 

Este exemplo renderiza uma biblioteca deck.gl da camada de arco do Google.

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

Para obter um exemplo totalmente funcional com código-fonte, confira a camada personalizada do Deck GL do WebGL nos exemplos do Azure Mapas.

Próximas etapas

Saiba mais sobre as classes e métodos usados neste artigo: