Update quadFeature documentation.
Also update some renderer documentation.
MODIFY
src/canvas/canvasRenderer.js
src/canvas/canvasRenderer.js
@@ -3,11 +3,12 @@ var registerRenderer = require('../registry').registerRenderer;
var renderer = require('../renderer');
/**
- * Create a new instance of class canvasRenderer
+ * Create a new instance of class canvasRenderer.
*
* @class geo.canvas.renderer
* @extends geo.renderer
- * @param canvas
+ * @param {object} arg Options for the renderer. This will typically have
+ * `layer` and `canvas`.
* @returns {geo.canvas.canvasRenderer}
*/
var canvasRenderer = function (arg) {
@@ -26,19 +27,29 @@ var canvasRenderer = function (arg) {
s_init = this._init,
s_exit = this._exit;
+ /**
+ * Set the clear canvas flag. If truthy, the canvas is erased at the start
+ * of the render cycle. If falsy, the old data is kept.
+ *
+ * @param {boolean} arg Truthy to clear the canvas when rendering is started.
+ */
this.clearCanvas = function (arg) {
m_clearCanvas = arg;
};
/**
- * Get API used by the renderer
+ * Get API used by the renderer.
+ *
+ * @returns {string} 'canvas'.
*/
this.api = function () {
return 'canvas';
};
/**
- * Initialize
+ * Initialize.
+ *
+ * @returns {this}
*/
this._init = function () {
if (m_this.initialized()) {
@@ -63,7 +74,13 @@ var canvasRenderer = function (arg) {
};
/**
- * Handle resize event
+ * Handle resize event.
+ *
+ * @param {number} x Ignored.
+ * @param {number} y Ignored.
+ * @param {number} w New width in pixels.
+ * @param {number} h New height in pixels.
+ * @returns {this}
*/
this._resize = function (x, y, w, h) {
m_this.canvas().attr('width', w);
@@ -74,7 +91,9 @@ var canvasRenderer = function (arg) {
};
/**
- * Render
+ * Render.
+ *
+ * @returns {this}
*/
this._render = function () {
m_this.layer().map().scheduleAnimationFrame(this._renderFrame);
@@ -88,7 +107,9 @@ var canvasRenderer = function (arg) {
var layer = m_this.layer(),
map = layer.map(),
camera = map.camera(),
- viewport = camera._viewport;
+ viewport = camera._viewport,
+ features = layer.features(),
+ i;
// Clear the canvas.
if (m_clearCanvas) {
@@ -96,8 +117,7 @@ var canvasRenderer = function (arg) {
m_this.context2d.clearRect(0, 0, viewport.width, viewport.height);
}
- var features = layer.features();
- for (var i = 0; i < features.length; i += 1) {
+ for (i = 0; i < features.length; i += 1) {
if (features[i].visible()) {
features[i]._renderOnCanvas(m_this.context2d, map);
}
@@ -105,7 +125,7 @@ var canvasRenderer = function (arg) {
};
/**
- * Exit
+ * Exit.
*/
this._exit = function () {
m_this.canvas().remove();
@@ -148,7 +168,7 @@ registerRenderer('canvas', canvasRenderer);
* If the canvas renderer is not supported, supply the name of a renderer that
* should be used instead. This asks for the null renderer.
*
- * @returns null for the null renderer.
+ * @returns {null} `null` for the null renderer.
*/
canvasRenderer.fallback = function () {
return null;

MODIFY
src/canvas/quadFeature.js
src/canvas/quadFeature.js
@@ -3,10 +3,10 @@ var registerFeature = require('../registry').registerFeature;
var quadFeature = require('../quadFeature');
/**
- * Create a new instance of class quadFeature
+ * Create a new instance of class quadFeature.
*
* @class geo.canvas.quadFeature
- * @param {Object} arg Options object
+ * @param {geo.quadFeature.spec} arg Options object.
* @extends geo.quadFeature
* @returns {geo.canvas.quadFeature}
*/
@@ -30,7 +30,7 @@ var canvas_quadFeature = function (arg) {
m_quads;
/**
- * Build this feature
+ * Build this feature.
*/
this._build = function () {
if (!m_this.position()) {
@@ -47,19 +47,20 @@ var canvas_quadFeature = function (arg) {
};
/**
- * Render all of the color quads using a single mapper.
+ * Render all of the color quads.
*
- * @param renderState: the render state used for the render.
+ * @param {CanvasRenderingContext2D} context2d The rendering context.
+ * @param {geo.map} map The current renderer's parent map.
*/
- this._renderColorQuads = function (renderState) {
- // ....
+ this._renderColorQuads = function (context2d, map) {
// Not implemented yet.
};
/**
- * Render all of the image quads using a single mapper.
+ * Render all of the image quads.
*
- * @param renderState: the render state used for the render.
+ * @param {CanvasRenderingContext2D} context2d The rendering context.
+ * @param {geo.map} map The current renderer's parent map.
*/
this._renderImageQuads = function (context2d, map) {
if (!m_quads.imgQuads.length) {
@@ -98,13 +99,19 @@ var canvas_quadFeature = function (arg) {
}
};
+ /**
+ * Render all of the quads.
+ *
+ * @param {CanvasRenderingContext2D} context The rendering context.
+ * @param {geo.map} map The current renderer's parent map.
+ */
this._renderOnCanvas = function (context, map) {
this._renderImageQuads(context, map);
this._renderColorQuads(context, map);
};
/**
- * Update
+ * Update.
*/
this._update = function () {
s_update.call(m_this);
@@ -117,14 +124,14 @@ var canvas_quadFeature = function (arg) {
};
/**
- * Initialize
+ * Initialize.
*/
this._init = function () {
s_init.call(m_this, arg);
};
/**
- * Destroy
+ * Destroy.
*/
this._exit = function () {

MODIFY
src/d3/quadFeature.js
src/d3/quadFeature.js
@@ -3,10 +3,10 @@ var registerFeature = require('../registry').registerFeature;
var quadFeature = require('../quadFeature');
/**
- * Create a new instance of class quadFeature
+ * Create a new instance of class quadFeature.
*
* @class geo.d3.quadFeature
- * @param {Object} arg Options object
+ * @param {geo.quadFeature.spec} arg Options object.
* @extends geo.quadFeature
* @returns {geo.d3.quadFeature}
*/
@@ -30,7 +30,7 @@ var d3_quadFeature = function (arg) {
m_quads;
/**
- * Build this feature
+ * Build this feature.
*/
this._build = function () {
if (!this.position()) {
@@ -187,7 +187,9 @@ var d3_quadFeature = function (arg) {
};
/**
- * Update
+ * Update the feature.
+ *
+ * @returns {this}
*/
this._update = function () {
s_update.call(m_this);
@@ -199,14 +201,14 @@ var d3_quadFeature = function (arg) {
};
/**
- * Initialize
+ * Initialize.
*/
this._init = function () {
s_init.call(m_this, arg);
};
/**
- * Destroy
+ * Destroy.
*/
this._exit = function () {
s_exit.call(m_this);

MODIFY
src/gl/quadFeature.js
src/gl/quadFeature.js
@@ -3,10 +3,10 @@ var registerFeature = require('../registry').registerFeature;
var quadFeature = require('../quadFeature');
/**
- * Create a new instance of class quadFeature
+ * Create a new instance of class quadFeature.
*
* @class geo.gl.quadFeature
- * @param {Object} arg Options object
+ * @param {geo.quadFeature.spec} arg Options object.
* @extends geo.quadFeature
* @returns {geo.gl.quadFeature}
*/
@@ -72,6 +72,8 @@ var gl_quadFeature = function (arg) {
* the actions from vgl.mapper to some degree.
*
* @private
+ * @param {vgl.renderState} renderState An object that contains the context
+ * used for drawing.
*/
function setupDrawObjects(renderState) {
var context = renderState.m_context,
@@ -108,6 +110,8 @@ var gl_quadFeature = function (arg) {
* the actions from vgl.mapper to some degree.
*
* @private
+ * @param {vgl.renderState} renderState An object that contains the context
+ * used for drawing.
*/
function setupColorDrawObjects(renderState) {
var context = renderState.m_context,
@@ -140,7 +144,7 @@ var gl_quadFeature = function (arg) {
}
/**
- * Build this feature
+ * Build this feature.
*/
this._build = function () {
var mapper, mat, prog, srctex, unicrop, geom;
@@ -262,7 +266,8 @@ var gl_quadFeature = function (arg) {
/**
* Render all of the color quads using a single mapper.
*
- * @param renderState: the render state used for the render.
+ * @param {vgl.renderState} renderState An object that contains the context
+ * used for drawing.
*/
this._renderColorQuads = function (renderState) {
if (!m_quads.clrQuads.length) {
@@ -308,7 +313,8 @@ var gl_quadFeature = function (arg) {
/**
* Render all of the image quads using a single mapper.
*
- * @param renderState: the render state used for the render.
+ * @param {vgl.renderState} renderState An object that contains the context
+ * used for drawing.
*/
this._renderImageQuads = function (renderState) {
if (!m_quads.imgQuads.length) {
@@ -358,7 +364,7 @@ var gl_quadFeature = function (arg) {
};
/**
- * Update
+ * Update.
*/
this._update = function () {
s_update.call(m_this);
@@ -378,14 +384,14 @@ var gl_quadFeature = function (arg) {
};
/**
- * Initialize
+ * Initialize.
*/
this._init = function () {
s_init.call(m_this, arg);
};
/**
- * Destroy
+ * Destroy.
*/
this._exit = function () {
if (m_actor_image) {

MODIFY
src/gl/vglRenderer.js
src/gl/vglRenderer.js
@@ -3,11 +3,13 @@ var registerRenderer = require('../registry').registerRenderer;
var renderer = require('../renderer');
/**
- * Create a new instance of class vglRenderer
+ * Create a new instance of class vglRenderer.
*
* @class geo.gl.vglRenderer
* @extends geo.renderer
- * @param canvas
+ * @param {object} [arg] Options for the renderer.
+ * @param {geo.layer} [arg.layer] The layer the renderer is associated with.
+ * @param {object} [arg.options] Additional options for the vgl renderer.
* @returns {geo.gl.vglRenderer}
*/
var vglRenderer = function (arg) {
@@ -37,35 +39,45 @@ var vglRenderer = function (arg) {
// TODO: Move this API to the base class
/**
- * Return width of the renderer
+ * Return width of the renderer.
+ *
+ * @returns {number} The width of the current canvas.
*/
this.width = function () {
return m_width;
};
/**
- * Return height of the renderer
+ * Return height of the renderer.
+ *
+ * @returns {number} The height of the current canvas.
*/
this.height = function () {
return m_height;
};
/**
- * Get context specific renderer
+ * Get context specific renderer.
+ *
+ * @returns {object} The vgl context renderer.
*/
this.contextRenderer = function () {
return m_contextRenderer;
};
/**
- * Get API used by the renderer
+ * Get API used by the renderer.
+ *
+ * @returns {string} `vgl`.
*/
this.api = function () {
return 'vgl';
};
/**
- * Initialize
+ * Initialize.
+ *
+ * @returns {this}
*/
this._init = function () {
if (m_this.initialized()) {
@@ -112,7 +124,13 @@ var vglRenderer = function (arg) {
};
/**
- * Handle resize event
+ * Handle resize event.
+ *
+ * @param {number} x The left coordinate.
+ * @param {number} y The top coordinate.
+ * @param {number} w The width in pixels.
+ * @param {number} h The height in pixels.
+ * @returns {this}
*/
this._resize = function (x, y, w, h) {
var renderWindow = m_viewer.renderWindow();
@@ -131,6 +149,8 @@ var vglRenderer = function (arg) {
/**
* Render. This actually schedules rendering for the next animation frame.
+ *
+ * @returns {this}
*/
this._render = function () {
/* If we are already scheduled to render, don't schedule again. Rather,
@@ -155,7 +175,7 @@ var vglRenderer = function (arg) {
};
/**
- * Exit
+ * Exit.
*/
this._exit = function () {
m_this.canvas().remove();
@@ -163,6 +183,9 @@ var vglRenderer = function (arg) {
s_exit();
};
+ /**
+ * Update the vgl renderer's camera based on the map's camera class.
+ */
this._updateRendererCamera = function () {
var renderWindow = m_viewer.renderWindow(),
map = m_this.layer().map(),
@@ -283,7 +306,7 @@ registerRenderer('vgl', vglRenderer);
exts = ctx.getSupportedExtensions();
checkedWebGL = true;
} catch (e) {
- console.error('No webGL support');
+ console.warn('No webGL support');
checkedWebGL = false;
}
canvas = undefined;
@@ -297,7 +320,7 @@ registerRenderer('vgl', vglRenderer);
* If the vgl renderer is not supported, supply the name of a renderer that
* should be used instead. This asks for the null renderer.
*
- * @returns null for the null renderer.
+ * @returns {null} null for the null renderer.
*/
vglRenderer.fallback = function () {
return null;

MODIFY
src/quadFeature.js
src/quadFeature.js
@@ -3,27 +3,25 @@ var inherit = require('./inherit');
var feature = require('./feature');
/**
- * Create a new instance of class quadFeature
+ * Quad feature specification.
*
- * @class geo.quadFeature
- * @param {Object} arg Options object
- * @extends geo.feature
- * @param {Object|string|Function} [color] Color for quads without images.
+ * @typedef {geo.feature.spec} geo.quadFeature.spec
+ * @param {geo.geoColor|Function} [color] Color for quads without images.
* Default is white ({r: 1, g: 1, b: 1}).
- * @param {number|Function} [opacity=1] Opacity for quad
+ * @param {number|Function} [opacity=1] Opacity for the quads.
* @param {number|Function} [depth=0] Default z-coordinate for positions that
* don't explicitly specify one.
* @param {boolean|Function} [drawOnAsyncResourceLoaded=true] Redraw quads
* when images are loaded after initial render.
* @param {Image|string|Function} [image] Image for each data item. If
- * undefined or null, the quad is a solid color. Default is (data).image.
- * @param {Object|string|Function} [previewColor=null] If specified, a color to
+ * falsy, the quad is a solid color. Default is (data).image.
+ * @param {geo.geoColor|Function} [previewColor=null] If specified, a color to
* show on image quads while waiting for the image to load.
* @param {Image|string|Function} [previewImage=null] If specified, an image to
* show on image quads while waiting for the quad-specific image to load.
* This will only be shown if it is already loaded.
- * @param {Object|Function} [position] Position of the quad. Default is
- * (data). The position is an Object which specifies the corners of the
+ * @param {object|Function} [position] Position of the quad. Default is
+ * (data). The position is an object which specifies the corners of the
* quad: ll, lr, ur, ul. At least two opposite corners must be specified.
* The corners do not have to physically correspond to the order specified,
* but rather correspond to that part of an image (if there is one). If a
@@ -34,11 +32,19 @@ var feature = require('./feature');
* triangles: (ll, lr, ul) and (ur, ul, lr). Nothing special is done for
* quads that are not convex or quads that have substantially different
* transformations for those two triangles.
- * @param {boolean} [cacheQuads=true] If true, a set of internal information is
- * stored on each data item in the _cachedQuad attribute. If this is false,
- * the data item is not altered. If the data (positions, opacity, etc,) of
- * individual quads will change, set this to false or delete the _cachedQuad
- * attribute of the data item.
+ * @param {boolean} [cacheQuads=true] If truthy, a set of internal information
+ * is stored on each data item in the _cachedQuad attribute. If this is
+ * falsy, the data item is not altered. If the data (positions, opacity,
+ * etc.) of individual quads will change, set this to `false` or delete the
+ * `_cachedQuad` attribute of the data item.
+ */
+
+/**
+ * Create a new instance of class quadFeature.
+ *
+ * @class geo.quadFeature
+ * @param {geo.quadFeature.spec} arg Options object.
+ * @extends geo.feature
* @returns {geo.quadFeature}
*/
var quadFeature = function (arg) {
@@ -65,10 +71,10 @@ var quadFeature = function (arg) {
/**
* Track a list of object->object mappings. The mappings are kept in a list.
- * This marks all known mappings as unused. If they are not marked used
- * before _objectListEnd is called, that function will remove them.
+ * This marks all known mappings as unused. If they are not marked as used
+ * before `_objectListEnd` is called, that function will remove them.
*
- * @param {array} list the list of mappings.
+ * @param {array} list The list of mappings.
*/
this._objectListStart = function (list) {
$.each(list, function (idx, item) {
@@ -78,12 +84,12 @@ var quadFeature = function (arg) {
/**
* Get the value from a list of object->object mappings. If the key object
- * is not present, return undefined. If found, the entry is marked as being
- * in use.
+ * is not present, return `undefined`. If found, the entry is marked as
+ * being in use.
*
- * @param {array} list the list of mappings.
- * @param {object} entry the key to search for.
- * @returns {object} the associated object or undefined.
+ * @param {array} list The list of mappings.
+ * @param {object} entry The key to search for.
+ * @returns {object} The associated object or undefined.
*/
this._objectListGet = function (list, entry) {
for (var i = 0; i < list.length; i += 1) {
@@ -100,9 +106,9 @@ var quadFeature = function (arg) {
* should not exist, or this will create a duplicate. The new entry is
* marked as being in use.
*
- * @param {array} list the list of mappings.
- * @param {object} entry the key to add.
- * @param {object} value the value to store with the entry.
+ * @param {array} list The list of mappings.
+ * @param {object} entry The key to add.
+ * @param {object} value The value to store with the entry.
*/
this._objectListAdd = function (list, entry, value) {
list.push({entry: entry, value: value, used: true});
@@ -111,7 +117,7 @@ var quadFeature = function (arg) {
/**
* Remove all unused entries from a list of object->object mappings.
*
- * @param {array} list the list of mappings.
+ * @param {array} list The list of mappings.
*/
this._objectListEnd = function (list) {
for (var i = list.length - 1; i >= 0; i -= 1) {
@@ -125,11 +131,10 @@ var quadFeature = function (arg) {
* Point search method for selection api. Returns markers containing the
* given point.
*
- * @memberof geo.quadFeature
- * @param {Object} coordinate coordinate in input gcs to check if it is
+ * @param {object} coordinate Coordinate in input gcs to check if it is
* located in any quad.
- * @returns {Object} an object with 'index': a list of quad indices, and
- * 'found': a list of quads that contain the specified coordinate.
+ * @returns {object} An object with `index`: a list of quad indices, and
+ * `found`: a list of quads that contain the specified coordinate.
*/
this.pointSearch = function (coordinate) {
var found = [], indices = [], extra = {},
@@ -191,11 +196,11 @@ var quadFeature = function (arg) {
};
/**
- * Get/Set position
+ * Get/Set position.
*
* @memberof geo.quadFeature
- * @param {object|function} [position] object or function that returns the
- * position of each quad.
+ * @param {object|Function} [val] Object or function that returns the
+ * position of each quad. `undefined` to get the current position value.
* @returns {geo.quadFeature}
*/
this.position = function (val) {
@@ -214,16 +219,16 @@ var quadFeature = function (arg) {
* complete information for the quad. This generates missing corners and z
* values.
*
- * @param {function} posFunc a function to call to get the position of a data
+ * @param {function} posFunc A function to call to get the position of a data
* item. It is passed (d, i).
- * @param {function} depthFunc a function to call to get the z-value of a
+ * @param {function} depthFunc A function to call to get the z-value of a
* data item. It is passed (d, i).
- * @param d a data item. Used to fetch position and possibly depth.
- * @param i the index within the data. Used to fetch position and possibly
- * depth.
- * @returns {Object|undefined} either an object with all four corners, or
- * undefined if no such object can be generated. The coordinates have been
- * converted to map coordinates.
+ * @param {object} d A data item. Used to fetch position and possibly depth.
+ * @param {number} i The index within the data. Used to fetch position and
+ * possibly depth.
+ * @returns {object|undefined} Either an object with all four corners, or
+ * `undefined` if no such object can be generated. The coordinates have
+ * been converted to map coordinates.
*/
this._positionToQuad = function (posFunc, depthFunc, d, i) {
var initPos = posFunc.call(m_this, d, i);
@@ -273,9 +278,10 @@ var quadFeature = function (arg) {
* improve precision, the smallest quads are the ones most in need of this
* benefit.
*
- * @returns {Object} An object with clrQuads and imgQuads, each of which is
- * an array, and origin, which is a triplet that is guaranteed to be one of
- * the quads corners for a quad with the smallest sum of diagonal lengths.
+ * @returns {object} An object with `clrQuads` and `imgQuads`, each of which
+ * is an array; and `origin`, which is a triplet that is guaranteed to be
+ * one of the quads' corners for a quad with the smallest sum of diagonal
+ * lengths.
*/
this._generateQuads = function () {
var posFunc = m_this.position(),
@@ -448,7 +454,9 @@ var quadFeature = function (arg) {
};
/**
- * Initialize
+ * Initialize.
+ *
+ * @param {geo.quadFeature.spec} arg Options for the feature.
*/
this._init = function (arg) {
arg = arg || {};
@@ -481,20 +489,12 @@ var quadFeature = function (arg) {
return m_this;
};
-/**
- * Object specification for a quad feature.
- *
- * @extends geo.feature.spec // need to make a jsdoc plugin for this to work
- * @typedef geo.quadFeature.spec
- * @type {object}
- */
-
/**
* Create a quadFeature from an object.
*
* @see {@link geo.feature.create}
- * @param {geo.layer} layer The layer to add the feature to
- * @param {geo.quadFeature.spec} spec The object specification
+ * @param {geo.layer} layer The layer to add the feature to.
+ * @param {geo.quadFeature.spec} spec The object specification.
* @returns {geo.quadFeature|null}
*/
quadFeature.create = function (layer, spec) {

Update quadFeature documentation.

Also update some renderer documentation.