--- title: "CubemapLayer | JavaScript maps SDK" description: "Documentation for MapTiler SDK" --- > For AI agents: a documentation index is available at [/llms.txt](https://docs.maptiler.com/llms.txt). Markdown versions of all pages are available by appending .md to any URL. # Class CubemapLayer`Maptiler` 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](https://docs.maptiler.com/sdk-js/api-reference/classes/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](https://docs.maptiler.com/sdk-js/api-reference/classes/Map/#triggerrepaint) and they should appropriately handle [MapContextEvent](https://docs.maptiler.com/sdk-js/api-reference/types/MapContextEvent/) with `webglcontextlost` and `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](https://docs.maptiler.com/sdk-js/api-reference/interfaces/CustomLayerInterface/#prerender) #### Example[](#example) Custom layer implemented as ES6 class ```typescript class NullIslandLayer { constructor() { this.id = 'null-island'; this.type = 'custom'; this.renderingMode = '2d'; } onAdd(map: maplibregl.Map, gl: WebGLRenderingContext | WebGL2RenderingContext) { 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() { 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, modelViewProjectionMatrix: matrix }: { gl: WebGLRenderingContext | WebGL2RenderingContext; modelViewProjectionMatrix: Float32Array; }) { gl.useProgram(this.program); gl.uniformMatrix4fv(gl.getUniformLocation(this.program, "u_matrix"), false, matrix); gl.drawArrays(gl.POINTS, 0, 1); } } map.on('load', () => { map.addLayer(new NullIslandLayer()); }); ``` #### Implements - [CustomLayerInterface](https://docs.maptiler.com/sdk-js/api-reference/interfaces/CustomLayerInterface/) ##### Index ### Constructors[](#constructors) [constructor](#constructor) ### Properties[](#properties) [currentFacesDefinitionKey](#currentfacesdefinitionkey) [id](#id) [renderingMode](#renderingmode) [type](#type) ### Methods[](#methods) [getConfig](#getconfig) [hide](#hide) [onAdd](#onadd) [onRemove](#onremove) [prerender](#prerender) [render](#render) [setAnimationActive](#setanimationactive) [setCubemap](#setcubemap) [shouldUpdate](#shouldupdate) [show](#show) [updateCubemap](#updatecubemap) [updateTexture](#updatetexture) ## Constructors[](#constructors-1) ### `Maptiler`constructor[](#constructor) - new CubemapLayer(     cubemapConfig: true | [CubemapLayerConstructorOptions](https://docs.maptiler.com/sdk-js/api-reference/types/CubemapLayerConstructorOptions/), ): CubemapLayer[](#constructorcubemaplayer) Creates a new instance of CubemapLayer #### Parameters - cubemapConfig: true | [CubemapLayerConstructorOptions](https://docs.maptiler.com/sdk-js/api-reference/types/CubemapLayerConstructorOptions/) Configuration options for the cubemap layer or `true` to use default options. Can specify faces, preset, path, and color properties to configure the cubemap. #### Returns CubemapLayer #### Remarks[](#remarks) You shouldn't have to use this class directly. Instead, use the `Map.setHalo` method to create and add a halo layer to the map. The constructor initializes the cubemap with the provided configuration. It processes the faces definition, sets up background colors, and determines whether to use a cubemap texture based on the provided options. ## Properties[](#properties-1) ### `Maptiler`currentFacesDefinitionKey[](#currentfacesdefinitionkey) currentFacesDefinitionKey: string = "" The key representing the current faces definition, used to diff / track changes in the cubemap faces. ### `Maptiler`id[](#id) id: string = "Cubemap Layer" A unique layer id. Implementation of [CustomLayerInterface](https://docs.maptiler.com/sdk-js/api-reference/interfaces/CustomLayerInterface/).[id](https://docs.maptiler.com/sdk-js/api-reference/interfaces/CustomLayerInterface/#id) ### `Maptiler`renderingMode[](#renderingmode) renderingMode: "2d" | "3d" | undefined = "3d" Either `"2d"` or `"3d"`. Defaults to `"2d"`. Implementation of [CustomLayerInterface](https://docs.maptiler.com/sdk-js/api-reference/interfaces/CustomLayerInterface/).[renderingMode](https://docs.maptiler.com/sdk-js/api-reference/interfaces/CustomLayerInterface/#renderingmode) ### `Maptiler`type[](#type) type: "custom" The layer's type. Must be `"custom"`. Implementation of [CustomLayerInterface](https://docs.maptiler.com/sdk-js/api-reference/interfaces/CustomLayerInterface/).[type](https://docs.maptiler.com/sdk-js/api-reference/interfaces/CustomLayerInterface/#type) ## Methods[](#methods-1) ### `Maptiler`getConfig[](#getconfig) - getConfig(): [CubemapLayerConstructorOptions](https://docs.maptiler.com/sdk-js/api-reference/types/CubemapLayerConstructorOptions/)[](#getconfig-1) Returns the current configuration options for the cubemap layer. #### Returns [CubemapLayerConstructorOptions](https://docs.maptiler.com/sdk-js/api-reference/types/CubemapLayerConstructorOptions/) The current configuration options. ### `Maptiler`hide[](#hide) - hide(): void[](#hide-1) Hides the cubemap layer by setting its visibility to "none". This method is used to remove the cubemap layer from the map without deleting it. #### Returns void ### `Maptiler`onAdd[](#onadd) - onAdd(map: [Map](https://docs.maptiler.com/sdk-js/api-reference/classes/Map/), gl: [WebGLRenderingContext](https://docs.maptiler.com/sdk-js/api-reference/interfaces/Externals.WebGLRenderingContext/) | [WebGL2RenderingContext](https://docs.maptiler.com/sdk-js/api-reference/interfaces/Externals.WebGL2RenderingContext/)): void[](#onadd-1) Called when the layer is added to the map. Initializes the cubemap and sets up the WebGL context. #### Parameters - map: [Map](https://docs.maptiler.com/sdk-js/api-reference/classes/Map/) The map instance to which this layer is added. - gl: [WebGLRenderingContext](https://docs.maptiler.com/sdk-js/api-reference/interfaces/Externals.WebGLRenderingContext/) | [WebGL2RenderingContext](https://docs.maptiler.com/sdk-js/api-reference/interfaces/Externals.WebGL2RenderingContext/) The WebGL context used for rendering. #### Returns void Implementation of [CustomLayerInterface](https://docs.maptiler.com/sdk-js/api-reference/interfaces/CustomLayerInterface/).[onAdd](https://docs.maptiler.com/sdk-js/api-reference/interfaces/CustomLayerInterface/#onadd) ### `Maptiler`onRemove[](#onremove) - onRemove(\_map: [Map](https://docs.maptiler.com/sdk-js/api-reference/classes/Map/), gl: [WebGLRenderingContext](https://docs.maptiler.com/sdk-js/api-reference/interfaces/Externals.WebGLRenderingContext/) | [WebGL2RenderingContext](https://docs.maptiler.com/sdk-js/api-reference/interfaces/Externals.WebGL2RenderingContext/)): void[](#onremove-1) Called when the layer is removed from the map. Cleans up the cubemap resources and WebGL buffers. #### Parameters - \_map: [Map](https://docs.maptiler.com/sdk-js/api-reference/classes/Map/) The map instance from which this layer is removed. - gl: [WebGLRenderingContext](https://docs.maptiler.com/sdk-js/api-reference/interfaces/Externals.WebGLRenderingContext/) | [WebGL2RenderingContext](https://docs.maptiler.com/sdk-js/api-reference/interfaces/Externals.WebGL2RenderingContext/) The WebGL context used for rendering. #### Returns void Implementation of [CustomLayerInterface](https://docs.maptiler.com/sdk-js/api-reference/interfaces/CustomLayerInterface/).[onRemove](https://docs.maptiler.com/sdk-js/api-reference/interfaces/CustomLayerInterface/#onremove) ### `Maptiler`prerender[](#prerender) - prerender(\_gl: [WebGLContext](https://docs.maptiler.com/sdk-js/api-reference/types/Externals.WebGLContext/), \_options: [CustomRenderMethodInput](https://docs.maptiler.com/sdk-js/api-reference/types/CustomRenderMethodInput/)): void[](#prerender-1) Called before the layer is rendered. Updates the cubemap texture with the current faces. #### Parameters - \_gl: [WebGLContext](https://docs.maptiler.com/sdk-js/api-reference/types/Externals.WebGLContext/) - \_options: [CustomRenderMethodInput](https://docs.maptiler.com/sdk-js/api-reference/types/CustomRenderMethodInput/) Additional options for the render method. #### Returns void Implementation of CustomLayerInterface.prerender ### `Maptiler`render[](#render) - render(     gl: [WebGLRenderingContext](https://docs.maptiler.com/sdk-js/api-reference/interfaces/Externals.WebGLRenderingContext/) | [WebGL2RenderingContext](https://docs.maptiler.com/sdk-js/api-reference/interfaces/Externals.WebGL2RenderingContext/),     \_options: [CustomRenderMethodInput](https://docs.maptiler.com/sdk-js/api-reference/types/CustomRenderMethodInput/), ): void[](#render-1) Renders the cubemap layer to the WebGL context. This method is called internally during the rendering phase of the map. #### Parameters - gl: [WebGLRenderingContext](https://docs.maptiler.com/sdk-js/api-reference/interfaces/Externals.WebGLRenderingContext/) | [WebGL2RenderingContext](https://docs.maptiler.com/sdk-js/api-reference/interfaces/Externals.WebGL2RenderingContext/) The WebGL context used for rendering. - \_options: [CustomRenderMethodInput](https://docs.maptiler.com/sdk-js/api-reference/types/CustomRenderMethodInput/) Additional options for the render method. #### Returns void #### Throws[](#throws) Error if the map, cubemap, or texture is undefined. Implementation of CustomLayerInterface.render ### `Maptiler`setAnimationActive[](#setanimationactive) - setAnimationActive(active: boolean): void[](#setanimationactive-1) #### Parameters - active: boolean #### Returns void ### `Maptiler`setCubemap[](#setcubemap) - setCubemap(spec: boolean | [CubemapDefinition](https://docs.maptiler.com/sdk-js/api-reference/types/CubemapDefinition/)): Promise[](#setcubemap-1) Sets the cubemap for the layer based on the provided definition. This method updates the cubemap faces, background color, and triggers a repaint of the map. #### Parameters - spec: boolean | [CubemapDefinition](https://docs.maptiler.com/sdk-js/api-reference/types/CubemapDefinition/) #### Returns Promise A promise that resolves when the cubemap is set and the map is updated. #### Remarks[](#remarks-1) This method checks if the provided cubemap definition has a color, and if so, it updates the background color. It also checks if the faces definition has changed compared to the current one, and if so, it updates the cubemap faces. Finally, it calls `updateCubemap` to apply the changes and trigger a repaint of the map. ### `Maptiler`shouldUpdate[](#shouldupdate) - shouldUpdate(newSpec?: boolean | [CubemapDefinition](https://docs.maptiler.com/sdk-js/api-reference/types/CubemapDefinition/)): boolean[](#shouldupdate-1) Checks if the cubemap needs to be updated based on the provided specification. #### Parameters - `Optional`newSpec: boolean | [CubemapDefinition](https://docs.maptiler.com/sdk-js/api-reference/types/CubemapDefinition/) #### Returns boolean True if the cubemap needs to be updated, false otherwise. ### `Maptiler`show[](#show) - show(): void[](#show-1) Shows the cubemap layer by setting its visibility to "visible". This method is used to make the cubemap layer visible on the map. #### Returns void ### `Maptiler`updateCubemap[](#updatecubemap) - updateCubemap(\_\_namedParameters?: { facesNeedUpdate: boolean }): void[](#updatecubemap-1) Updates the cubemap object with the current faces and shader configuration. This method is called when the cubemap faces change or when the layer is initialized. #### Parameters - \_\_namedParameters: { facesNeedUpdate: boolean } = ... #### Returns void #### Remarks[](#remarks-2) It creates a new Object3D instance with the specified vertex and fragment shaders, attributes, and uniforms. The cubemap will be rendered using this configuration. ### `Maptiler`updateTexture[](#updatetexture) - updateTexture(gl: [WebGLContext](https://docs.maptiler.com/sdk-js/api-reference/types/Externals.WebGLContext/), faces: [CubemapFaces](https://docs.maptiler.com/sdk-js/api-reference/types/CubemapFaces/)): void[](#updatetexture-1) Updates the cubemap texture with the provided faces. This method is called when the cubemap faces change or when the layer is initialized. #### Parameters - gl: [WebGLContext](https://docs.maptiler.com/sdk-js/api-reference/types/Externals.WebGLContext/) The WebGL context used for rendering. - faces: [CubemapFaces](https://docs.maptiler.com/sdk-js/api-reference/types/CubemapFaces/) The cubemap faces to be loaded into the texture. #### Returns void