BaseLayers and Overlays

What's the difference?

OpenLayers as of Release 2.0 has support for two distinct types of layers: BaseLayers and Overlays. When you open the LayerSwitcher?, you will see that the two different types of layers are separated: BaseLayers are mutually exclusive and are selectable by radio-buttons, Overlays are not exclusive and can be turned on and off via checkboxes.

OpenLayers makes this distinction among its layers to allow the user to display data over multiple maps in different projections. When the projection of the underlying map layer (the BaseLayer) changes, all vector data must be reprojected.

Defaults

To determine whether a layer is a BaseLayer or Overlay, OpenLayers.Layer? defines a boolean property isBaseLayer.

In the definition of OpenLayers.Layer?, isBaseLayer is set to false, so any new Layer which is subclassed directly off of OpenLayers.Layer? will by default be an Overlay.

The following layers override and set isBaseLayer to true (are BaseLayers by default):

• OpenLayers.Layer.EventPane?
  • OpenLayers.Layer.Google?
  • OpenLayers.Layer.VirtualEarth?
• OpenLayers.Layer.KaMap
• OpenLayers.Layer.WFS?
• OpenLayers.Layer.WorldWind?

The following layers are Overlays by default (isBaseLayer: false):

• OpenLayers.Layer.Markers?
  • OpenLayers.Layer.GeoRSS?
  • OpenLayers.Layer.Text?

Overriding the defaults - Declaring a Layer? as a BaseLayer or Overlay

If the user wishes to to make a Layer? which is normally a BaseLayer into an Overlay (or viceversa), the isBaseLayer property must be changed. This can be specified on the layer's initialization, or by calling its setIsBaseLayer() function afterwards.

Examples: Setting isBaseLayer on initialization:

    var map = new OpenLayers.Map('map');
    var ol_wms = new OpenLayers.Layer.WMS.Untiled( "OpenLayers WMS", 
        "http://labs.metacarta.com/wms/vmap0?", {layers: 'basic'}, 
        { isBaseLayer: true} );
    map.addLayer(ol_wms);
    map.setCenter(new OpenLayers.LonLat(0, 0), 0);

or Setting isBaseLayer after initialization:

    var map = new OpenLayers.Map('map');
    var ol_wms = new OpenLayers.Layer.WMS.Untiled( "OpenLayers WMS", 
        "http://labs.metacarta.com/wms/vmap0?", {layers: 'basic'});
    ol_wms.setIsBaseLayer(true);
    map.addLayer(ol_wms);
    map.setCenter(new OpenLayers.LonLat(0, 0), 0);