Merge pull request #147 from ahocevar/custom-synchronizers

Allow working with custom synchronizers

Author: ahocevar

build/jsdoc/api/conf.json

@@ -10,7 +10,8 @@
         "includePattern": ".+\\.js(doc)?$",
         "excludePattern": "(^|\\/|\\\\)_",
         "include": [
-            "src"
+            "src",
+            "externs"
         ]
     },
     "plugins": [

build/jsdoc/api/plugins/typedefs.js

@@ -1,19 +1,19 @@
 /*
- * Converts olx.js @type annotations into properties of the previous @typedef.
+ * Converts olcsx.js @type annotations into properties of the previous @typedef.
  * Changes @enum annotations into @typedef.
  */
 
-var lastOlxTypedef = null;
-var olxTypes = {};
+var lastOlcsxTypedef = null;
+var olcsxTypes = {};
 
 function addSubparams(params) {
   for (var j = 0, jj = params.length; j < jj; ++j) {
     var param = params[j];
     var types = param.type.names;
     for (var k = 0, kk = types.length; k < kk; ++k) {
       var name = types[k];
-      if (name in olxTypes) {
-        param.subparams = olxTypes[name];
+      if (name in olcsxTypes) {
+        param.subparams = olcsxTypes[name];
         // TODO addSubparams(param.subparams);
         // TODO Do we need to support multiple object literal types per
         // param?
@@ -27,20 +27,20 @@ exports.handlers = {
 
   newDoclet: function(e) {
     var doclet = e.doclet;
-    if (doclet.meta.filename == 'olx.js') {
+    if (doclet.meta.filename == 'olcsx.js') {
       // do nothing if not marked @api
       if (!doclet.stability) {
         return;
       }
       if (doclet.kind == 'typedef') {
-        lastOlxTypedef = doclet;
-        olxTypes[doclet.longname] = [];
+        lastOlcsxTypedef = doclet;
+        olcsxTypes[doclet.longname] = [];
         doclet.properties = [];
-      } else if (lastOlxTypedef && doclet.memberof == lastOlxTypedef.longname) {
-        lastOlxTypedef.properties.push(doclet);
-        olxTypes[lastOlxTypedef.longname].push(doclet);
+      } else if (lastOlcsxTypedef && doclet.memberof == lastOlcsxTypedef.longname) {
+        lastOlcsxTypedef.properties.push(doclet);
+        olcsxTypes[lastOlcsxTypedef.longname].push(doclet);
       } else {
-        lastOlxTypedef = null;
+        lastOlcsxTypedef = null;
       }
     } else if (doclet.isEnum) {
       // We never export enums, so we document them like typedefs

externs/olcsx.js

@@ -5,6 +5,45 @@
  */
 var olcsx;
 
+
+/**
+ * @typedef {{
+ *   map: (!ol.Map),
+ *   target: (Element|string|undefined),
+ *   createSynchronizers: ((function(!ol.Map, !Cesium.Scene): Array.<olcs.AbstractSynchronizer>)|undefined)
+ * }}
+ * @api
+ */
+olcsx.OLCesiumOptions;
+
+
+/**
+ * The OpenLayers map we want to show on a Cesium scene.
+ * @type {!ol.Map}
+ * @api
+ */
+olcsx.OLCesiumOptions.prototype.map;
+
+
+/**
+ * Target element for the Cesium scene.
+ * @type {Element|string|undefined}
+ * @api
+ */
+olcsx.OLCesiumOptions.prototype.target;
+
+
+/**
+ * Callback function which will be called by the {@link olcs.OLCesium}
+ * constructor to create custom synchronizers. Receives an `ol.Map` and a
+ * `Cesium.Scene` as arguments, and needs to return an array of
+ * {@link olcs.AbstractSynchronizer}.
+ * @type {undefined|function(!ol.Map, !Cesium.Scene): Array.<olcs.AbstractSynchronizer>}
+ * @api
+ */
+olcsx.OLCesiumOptions.prototype.createSynchronizers;
+
+
 /**
  * Core namespace.
  * @type {Object}

src/ol3cesium.js

@@ -11,12 +11,24 @@ goog.require('olcs.VectorSynchronizer');
 
 
 /**
- * @param {!ol.Map} map
+ * @param {!(olcsx.OLCesiumOptions|ol.Map)} options Options.
  * @param {Element|string=} opt_target Target element for the Cesium container.
+ *   Use the `target` option in `options` instead.
  * @constructor
  * @api
  */
-olcs.OLCesium = function(map, opt_target) {
+olcs.OLCesium = function(options, opt_target) {
+
+  var map, createSynchronizers;
+  var target = opt_target;
+  if (options instanceof ol.Map) {
+    map = options;
+  } else {
+    map = options.map;
+    target = options.target;
+    createSynchronizers = options.createSynchronizers;
+  }
+
   /**
    * @type {!ol.Map}
    * @private
@@ -32,7 +44,7 @@ olcs.OLCesium = function(map, opt_target) {
   this.container_ = goog.dom.createDom(goog.dom.TagName.DIV,
       {style: fillArea + 'visibility:hidden;'});
 
-  var targetElement = goog.dom.getElement(opt_target || null);
+  var targetElement = goog.dom.getElement(target || null);
   if (targetElement) {
     goog.dom.appendChild(targetElement, this.container_);
   } else {
@@ -121,17 +133,16 @@ olcs.OLCesium = function(map, opt_target) {
   this.scene_.globe = this.globe_;
   this.scene_.skyAtmosphere = new Cesium.SkyAtmosphere();
 
-  /**
-   * @type {!olcs.RasterSynchronizer}
-   * @private
-   */
-  this.rasterSynchronizer_ = new olcs.RasterSynchronizer(this.map_,
-      this.scene_);
-  this.rasterSynchronizer_.synchronize();
+  var synchronizers = goog.isDef(createSynchronizers) ?
+      createSynchronizers(this.map_, this.scene_) :
+      [
+        new olcs.RasterSynchronizer(this.map_, this.scene_),
+        new olcs.VectorSynchronizer(this.map_, this.scene_)
+      ];
 
-  this.vectorSynchronizer_ = new olcs.VectorSynchronizer(this.map_,
-      this.scene_);
-  this.vectorSynchronizer_.synchronize();
+  for (var i = synchronizers.length - 1; i >= 0; --i) {
+    synchronizers[i].synchronize();
+  }
 
   if (this.isOverMap_) {
     // if in "stacked mode", hide everything except canvas (including credits)