Properties and options

Goong GL JS's global properties and options that you can access while initializing your map or accessing information about its status.

accessToken

Gets and sets the map's access token.

Example
goongjs.accessToken = myAccessToken;

Related

baseApiUrl

Gets and sets the map's default API URL for requesting tiles, styles, sprites, and glyphs

Example
goongjs.baseApiUrl = 'https://api.goong.io';

workerCount

Gets and sets the number of web workers instantiated on a page with GL JS maps. By default, it is set to half the number of CPU cores (capped at 6). Make sure to set this property before creating any map instances for it to have effect.

Example
goongjs.workerCount = 2;

maxParallelImageRequests

Gets and sets the maximum number of images (raster tiles, sprites, icons) to load in parallel, which affects performance in raster-heavy maps. 16 by default.

Example
goongjs.maxParallelImageRequests = 10;

supported

Test whether the browser supports Goong GL JS.

Parameters

options (Object?)

NameDescription
options.failIfMajorPerformanceCaveat
boolean
default: false
If true , the function will return false if the performance of Goong GL JS would be dramatically worse than expected (e.g. a software WebGL renderer would be used).
Returns

boolean:

Example
goongjs.supported() // = true

Related

version

The version of Goong GL JS in use as specified in package.json, CHANGELOG.md, and the GitHub release

setRTLTextPlugin

Sets the map's RTL text plugin. Necessary for supporting the Arabic and Hebrew languages, which are written right-to-left. Mapbox Studio loads this plugin by default.

Parameters

pluginURL (string)URL pointing to the Mapbox RTL text plugin source.

callback (Function)Called with an error argument if there is an error.

lazy (boolean)If set to true , goongjs will defer loading the plugin until rtl text is encountered, rtl text will then be rendered only after the plugin finishes loading.

Example
goongjs.setRTLTextPlugin('https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-rtl-text/v0.2.0/mapbox-gl-rtl-text.js');

Related

getRTLTextPluginStatus

Gets the map's RTL text plugin status. The status can be unavailable (i.e. not requested or removed), loading, loaded or error. If the status is loaded and the plugin is requested again, an error will be thrown.

Example
const pluginStatus = goongjs.getRTLTextPluginStatus();

clearStorage

Clears browser storage used by this library. Using this method flushes the Mapbox tile cache that is managed by this library. Tiles may still be cached by the browser in some cases.

This API is supported on browsers where the Cache API is supported and enabled. This includes all major browsers when pages are served over https://, except Internet Explorer and Edge Mobile.

When called in unsupported browsers or environments (private or incognito mode), the callback will be called with an error argument.

Parameters

callback (Function)Called with an error argument if there is an error.

AnimationOptions

Options common to map movement methods that involve animation, such as Map#panBy and Map#easeTo, controlling the duration and easing function of the animation. All properties are optional.

Properties

duration (number): The animation's duration, measured in milliseconds.

easing (Function): A function taking a time in the range 0..1 and returning a number where 0 is the initial state and 1 is the final state.

offset (PointLike): of the target center relative to real map container center at the end of animation.

animate (boolean): If false , no animation will occur.

essential (boolean): If true , then the animation is considered essential and will not be affected by prefers-reduced-motion.

CameraOptions

Options common to Map#jumpTo, Map#easeTo, and Map#flyTo, controlling the desired location, zoom, bearing, and pitch of the camera. All properties are optional, and when a property is omitted, the current camera value for that property will remain unchanged.

Properties

center (LngLatLike): The desired center.

zoom (number): The desired zoom level.

bearing (number): The desired bearing, in degrees. The bearing is the compass direction that is "up"; for example, a bearing of 90° orients the map so that east is up.

pitch (number): The desired pitch, in degrees.

around (LngLatLike): If zoom is specified, around determines the point around which the zoom is centered.

PaddingOptions

Options for setting padding on a call to Map#fitBounds. All properties of this object must be non-negative integers.

Properties

top (number): Padding in pixels from the top of the map canvas.

bottom (number): Padding in pixels from the bottom of the map canvas.

left (number): Padding in pixels from the left of the map canvas.

right (number): Padding in pixels from the right of the map canvas

RequestParameters

A RequestParameters object to be returned from Map.options.transformRequest callbacks.

Properties

url (string): The URL to be requested.

headers (Object): The headers to be sent with the request.

credentials (string): 'same-origin'|'include' Use 'include' to send cookies with cross-origin requests.

StyleImageInterface

Interface for dynamically generated style images. This is a specification for implementers to model: it is not an exported method or class.

Images implementing this interface can be redrawn for every frame. They can be used to animate icons and patterns or make them respond to user input. Style images can implement a StyleImageInterface#render method. The method is called every frame and can be used to update the image.

Properties

width (number)

height (number)

data ((Uint8Array|Uint8ClampedArray))

Example
var flashingSquare = {
    width: 64,
    height: 64,
    data: new Uint8Array(64 * 64 * 4),
    
    onAdd: function(map) {
        this.map = map;
    },
    
    render: function() {
        // keep repainting while the icon is on the map
        this.map.triggerRepaint();
    
        // alternate between black and white based on the time
        var value = Math.round(Date.now() / 1000) % 2 === 0  ? 255 : 0;
        
        // check if image needs to be changed
        if (value !== this.previousValue) {
            this.previousValue = value;
            
            var bytesPerPixel = 4;
            for (var x = 0; x < this.width; x++) {
            for (var y = 0; y < this.height; y++) {
            var offset = (y * this.width + x) * bytesPerPixel;
            this.data[offset + 0] = value;
            this.data[offset + 1] = value;
            this.data[offset + 2] = value;
            this.data[offset + 3] = 255;
            }
          }
            
      // return true to indicate that the image changed
      return true;
    }
  }
}
            
map.addImage('flashing_square', flashingSquare);

Instance Members

Optional method called when the layer has been added to the Map with Map#addImage.

Parameters

map (Map)The Map this custom layer was just added to.

Optional method called when the icon is removed from the map with Map#removeImage. This gives the image a chance to clean up resources and event listeners.

This method is called once before every frame where the icon will be used. The method can optionally update the image's data member with a new image.

If the method updates the image it must return true to commit the change. If the method returns false or nothing the image is assumed to not have changed.

If updates are infrequent it maybe easier to use Map#updateImage to update the image instead of implementing this method.

Returns

boolean: true if this method updated the image. false if the image was not changed.

Related

CustomLayerInterface

Interface for custom style layers. This is a specification for implementers to model: it is not an exported method or class.

Custom layers allow a user to render directly into the map's GL context using the map's camera. These layers can be added between any regular layers using Map#addLayer.

Custom layers must have a unique id and must have the type of "custom". They must implement render and may implement prerender, onAdd and onRemove. They can trigger rendering using Map#triggerRepaint and they should appropriately handle Map.event:webglcontextlost and Map.event:webglcontextrestored.

The renderingMode property controls whether the layer is treated as a "2d" or "3d" map layer. Use:

  • "renderingMode": "3d" to use the depth buffer and share it with other layers
  • "renderingMode": "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 CustomLayerInterface#prerender

Properties

id (string): A unique layer id.

type (string): The layer's type. Must be "custom".

renderingMode (string): Either "2d" or "3d" . Defaults to "2d".

Example
// Custom layer implemented as ES6 class
class NullIslandLayer {
    constructor() {
        this.id = 'null-island';
        this.type = 'custom';
        this.renderingMode = '2d';
    }

    onAdd(map, gl) {
        const vertexSource = `
        uniform mat4 u_matrix;
        void main() {
            gl_Position = u_matrix * vec4(0.5, 0.5, 0.0, 1.0);
            gl_PointSize = 20.0;
        }`;

        const fragmentSource = `
        void main() {
            gl_FragColor = vec4(1.0, 0.0, 0.0, 1.0);
        }`;

        const vertexShader = gl.createShader(gl.VERTEX_SHADER);
        gl.shaderSource(vertexShader, vertexSource);
        gl.compileShader(vertexShader);
        const fragmentShader = gl.createShader(gl.FRAGMENT_SHADER);
        gl.shaderSource(fragmentShader, fragmentSource);
        gl.compileShader(fragmentShader);

        this.program = gl.createProgram();
        gl.attachShader(this.program, vertexShader);
        gl.attachShader(this.program, fragmentShader);
        gl.linkProgram(this.program);
    }

    render(gl, matrix) {
        gl.useProgram(this.program);
        gl.uniformMatrix4fv(gl.getUniformLocation(this.program, "u_matrix"), false, matrix);
        gl.drawArrays(gl.POINTS, 0, 1);
    }
}

map.on('load', function() {
    map.addLayer(new NullIslandLayer());
});

Instance Members

Optional method called when the layer has been added to the Map with Map#addLayer. This gives the layer a chance to initialize gl resources and register event listeners.

Parameters

map (Map)The Map this custom layer was just added to.

gl (WebGLRenderingContext)The gl context for the map.

Optional method called when the layer has been removed from the Map with Map#removeLayer. This gives the layer a chance to clean up gl resources and event listeners.

Parameters

map (Map)The Map this custom layer was just added to.

gl (WebGLRenderingContext)The gl context for the map.

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.

Parameters

gl (WebGLRenderingContext)The map's gl context.

matrix (Array<number>)The map's camera matrix. It projects spherical mercator coordinates to gl coordinates. The spherical mercator coordinate [0, 0] represents the top left corner of the mercator world and [1, 1] represents the bottom right corner. When the renderingMode is "3d" , the z coordinate is conformal. A box with identical x, y, and z lengths in mercator units would be rendered as a cube. MercatorCoordinate .fromLatLng can be used to project a LngLat to a mercator coordinate.

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

Parameters

gl (WebGLRenderingContext)The map's gl context.

matrix (Array<number>)The map's camera matrix. It projects spherical mercator coordinates to gl coordinates. The spherical mercator coordinate [0, 0] represents the top left corner of the mercator world and [1, 1] represents the bottom right corner. When the renderingMode is "3d" , the z coordinate is conformal. A box with identical x, y, and z lengths in mercator units would be rendered as a cube. MercatorCoordinate .fromLatLng can be used to project a LngLat to a mercator coordinate.