From d5a3cabf137b62cb2920694fa03c852428729aec Mon Sep 17 00:00:00 2001 From: Tom Date: Mon, 18 Dec 2023 17:01:17 -0500 Subject: [PATCH] fixing jsdocs --- src/drawerbase.js | 7 ++-- src/htmldrawer.js | 7 ++-- src/imageloader.js | 4 ++ src/matrix.js | 97 ++++++++++++++++++++++++++++++++++++++++--- src/openseadragon.js | 23 +++++----- src/referencestrip.js | 2 +- src/tiledimage.js | 24 +++++------ src/viewer.js | 2 +- 8 files changed, 129 insertions(+), 37 deletions(-) diff --git a/src/drawerbase.js b/src/drawerbase.js index 05c8e888..c976147f 100644 --- a/src/drawerbase.js +++ b/src/drawerbase.js @@ -176,10 +176,11 @@ $.DrawerBase = class DrawerBase{ // Private functions /** - * @private * Ensures that child classes have provided implementations for public API methods * draw, canRotate, destroy, and setImageSmoothinEnabled. Throws an exception if the original * placeholder methods are still in place. + * @private + * */ _checkForAPIOverrides(){ if(this._createDrawingElement === $.DrawerBase.prototype._createDrawingElement){ @@ -240,9 +241,9 @@ $.DrawerBase = class DrawerBase{ // Internal utility functions /** - * @private - * Calculate width and height of the canvas based on viewport dimensions + * * Calculate width and height of the canvas based on viewport dimensions * and pixelDensityRatio + * @private * @returns {OpenSeadragon.Point} {x, y} size of the canvas */ _calculateCanvasSize() { diff --git a/src/htmldrawer.js b/src/htmldrawer.js index 342e157f..2469369c 100644 --- a/src/htmldrawer.js +++ b/src/htmldrawer.js @@ -102,7 +102,6 @@ class HTMLDrawer extends $.DrawerBase{ * Destroy the drawer (unload current loaded tiles) */ destroy() { - //force unloading of current canvas (1x1 will be gc later, trick not necessarily needed) this.canvas.innerHTML = ""; } @@ -120,8 +119,8 @@ class HTMLDrawer extends $.DrawerBase{ } /** - * @private * Clears the Drawer so it's ready to draw another frame. + * @private * */ _prepareNewFrame() { @@ -129,8 +128,8 @@ class HTMLDrawer extends $.DrawerBase{ } /** - * @private * Draws a TiledImage. + * @private * */ _drawTiles( tiledImage ) { @@ -167,8 +166,8 @@ class HTMLDrawer extends $.DrawerBase{ } /** - * @private * Draws the given tile. + * @private * @param {OpenSeadragon.Tile} tile - The tile to draw. * @param {Function} drawingHandler - Method for firing the drawing event if using canvas. * drawingHandler({context, tile, rendered}) diff --git a/src/imageloader.js b/src/imageloader.js index 50ccac65..00e413c1 100644 --- a/src/imageloader.js +++ b/src/imageloader.js @@ -37,6 +37,8 @@ /** * @class ImageJob * @classdesc Handles downloading of a single image. + * + * @memberof OpenSeadragon * @param {Object} options - Options for this ImageJob. * @param {String} [options.src] - URL of image to download. * @param {Tile} [options.tile] - Tile that belongs the data to. @@ -87,6 +89,7 @@ $.ImageJob.prototype = { /** * Starts the image job. * @method + * @memberof OpenSeadragon.ImageJob# */ start: function() { this.tries++; @@ -113,6 +116,7 @@ $.ImageJob.prototype = { * @param {*} data data that has been downloaded * @param {XMLHttpRequest} request reference to the request if used * @param {string} errorMessage description upon failure + * @memberof OpenSeadragon.ImageJob# */ finish: function(data, request, errorMessage ) { this.data = data; diff --git a/src/matrix.js b/src/matrix.js index 59d57ab5..129eab99 100644 --- a/src/matrix.js +++ b/src/matrix.js @@ -1,8 +1,7 @@ /* * OpenSeadragon - Mat3 * - * Modified from https://webglfundamentals.org/webgl/lessons/webgl-2d-matrices.html - * Copyright (C) 2010-2024 webglfundamentals.org and OpenSeadragon contributors + * Copyright (C) 2010-2024 OpenSeadragon contributors * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions are @@ -30,14 +29,62 @@ * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + * + * + * + * Portions of this source file are taken from WegGL Fundamentals: + * + * # Copyright 2012, Gregg Tavares. + * # All rights reserved. + * # + * # Redistribution and use in source and binary forms, with or without + * # modification, are permitted provided that the following conditions are + * # met: + * # + * # * Redistributions of source code must retain the above copyright + * # notice, this list of conditions and the following disclaimer. + * # * Redistributions in binary form must reproduce the above + * # copyright notice, this list of conditions and the following disclaimer + * # in the documentation and/or other materials provided with the + * # distribution. + * # * Neither the name of Gregg Tavares. nor the names of his + * # contributors may be used to endorse or promote products derived from + * # this software without specific prior written permission. + * # + * # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + * # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + * # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + * # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT + * # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + * # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + * # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + * # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY + * # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + * # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE + * # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ + + + (function( $ ){ +// Modified from https://webglfundamentals.org/webgl/lessons/webgl-2d-matrices.html + /** - * Matrix left-to-right system representation - */ -$.Mat3 = class Mat3 { + * + * + * @class Mat3 + * @classdesc A left-to-right matrix representation, useful for affine transforms for + * positioning tiles for drawing + * + * @memberof OpenSeadragon + * + * @param {Array} [values] - Initial values for the matrix + * + **/ +class Mat3{ + constructor(values){ if(!values) { values = [ @@ -50,6 +97,12 @@ $.Mat3 = class Mat3 { this.values = values; } + /** + * @alias makeIdentity + * @memberof! OpenSeadragon.Mat3 + * @static + * @returns {OpenSeadragon.Mat3} an identity matrix + */ static makeIdentity(){ return new Mat3([ 1, 0, 0, @@ -58,6 +111,14 @@ $.Mat3 = class Mat3 { ]); } + /** + * @alias makeTranslation + * @memberof! OpenSeadragon.Mat3 + * @static + * @param {Number} tx The x value of the translation + * @param {Number} ty The y value of the translation + * @returns {OpenSeadragon.Mat3} A translation matrix + */ static makeTranslation(tx, ty) { return new Mat3([ 1, 0, 0, @@ -66,6 +127,13 @@ $.Mat3 = class Mat3 { ]); } + /** + * @alias makeRotation + * @memberof! OpenSeadragon.Mat3 + * @static + * @param {Number} angleInRadians The desired rotation angle, in radians + * @returns {OpenSeadragon.Mat3} A rotation matrix + */ static makeRotation(angleInRadians) { var c = Math.cos(angleInRadians); var s = Math.sin(angleInRadians); @@ -76,6 +144,14 @@ $.Mat3 = class Mat3 { ]); } + /** + * @alias makeScaling + * @memberof! OpenSeadragon.Mat3 + * @static + * @param {Number} sx The x value of the scaling + * @param {Number} sy The y value of the scaling + * @returns {OpenSeadragon.Mat3} A scaling matrix + */ static makeScaling(sx, sy) { return new Mat3([ sx, 0, 0, @@ -84,6 +160,12 @@ $.Mat3 = class Mat3 { ]); } + /** + * @alias multiply + * @memberof! OpenSeadragon.Mat3 + * @param {OpenSeadragon.Mat3} other the matrix to multiply with + * @returns {OpenSeadragon.Mat3} The result of matrix multiplication + */ multiply(other) { let a = this.values; let b = other.values; @@ -118,6 +200,9 @@ $.Mat3 = class Mat3 { b20 * a02 + b21 * a12 + b22 * a22, ]); } -}; +} + + +$.Mat3 = Mat3; }( OpenSeadragon )); diff --git a/src/openseadragon.js b/src/openseadragon.js index bcff91d0..66cf70a5 100644 --- a/src/openseadragon.js +++ b/src/openseadragon.js @@ -198,7 +198,7 @@ * * @property {Object} drawerOptions * Options to pass to the selected drawer implementation. For details - * please @see {@link drawerOptions}. + * please see {@link OpenSeadragon.DrawerOptions}. * * @property {Number} [opacity=1] * Default proportional opacity of the tiled images (1=opaque, 0=hidden) @@ -518,7 +518,7 @@ * Milliseconds to wait after each tile retry if tileRetryMax is set. * * @property {Boolean} [useCanvas=true] - * Deprecated. Use drawer option to specify preferred renderer. + * Deprecated. Use options.drawer to specify preferred renderer. * * @property {Number} [minPixelRatio=0.5] * The higher the minPixelRatio, the lower the quality of the image that @@ -754,6 +754,16 @@ * */ + /** + * @typedef {Object} DrawerOptions + * @memberof OpenSeadragon + * @property {Object} webgl - options if the WebGLDrawer is used. No options are currently supported. + * @property {Object} canvas - options if the CanvasDrawer is used. No options are currently supported. + * @property {Object} html - options if the HTMLDrawer is used. No options are currently supported. + * @property {Object} custom - options if a custom drawer is used. No options are currently supported. + */ + + /** * The names for the image resources used for the image navigation buttons. * @@ -1354,14 +1364,7 @@ function OpenSeadragon( options ){ // DRAWER SETTINGS drawer: ['webgl', 'canvas', 'html'], // prefer using webgl, then canvas (i.e. context2d), then fallback to html - /** - * drawerOptions dictionary. - * @type {Object} - * @property {Object} webgl - options if the WebGLDrawer is used. No options are currently supported. - * @property {Object} canvas - options if the CanvasDrawer is used. No options are currently supported. - * @property {Object} html - options if the HTMLDrawer is used. No options are currently supported. - * @property {Object} custom - options if a custom drawer is used. No options are currently supported. - */ + drawerOptions: { webgl: { diff --git a/src/referencestrip.js b/src/referencestrip.js index 9e15852d..bcf2cc85 100644 --- a/src/referencestrip.js +++ b/src/referencestrip.js @@ -455,7 +455,7 @@ function loadPanels( strip, viewerSize, scroll ) { animationTime: 0, loadTilesWithAjax: strip.viewer.loadTilesWithAjax, ajaxHeaders: strip.viewer.ajaxHeaders, - drawer: strip.viewer.drawerOptions.constructor, + drawer: strip.viewer.drawer.constructor, } ); // Allow pointer events to pass through miniViewer's canvas/container // elements so implicit pointer capture works on touch devices diff --git a/src/tiledimage.js b/src/tiledimage.js index c226c08a..8cc09e6c 100644 --- a/src/tiledimage.js +++ b/src/tiledimage.js @@ -1416,8 +1416,8 @@ $.extend($.TiledImage.prototype, $.EventSource.prototype, /** @lends OpenSeadrag }, /** - * @private * Update all tiles that contribute to the current view + * @private * */ _updateTilesInViewport: function(tiles) { @@ -1473,11 +1473,11 @@ $.extend($.TiledImage.prototype, $.EventSource.prototype, /** @lends OpenSeadrag }, /** - * @private * Updates the opacity of a tile according to the time it has been on screen * to perform a fade-in. * Updates coverage once a tile is fully opaque. * Returns whether the fade-in has completed. + * @private * * @param {OpenSeadragon.Tile} tile * @param {Number} x @@ -1690,8 +1690,8 @@ $.extend($.TiledImage.prototype, $.EventSource.prototype, /** @lends OpenSeadrag }, /** - * @private * Update a single tile at a particular resolution level. + * @private * @param {Boolean} haveDrawn * @param {Boolean} drawLevel * @param {Number} x @@ -1835,8 +1835,8 @@ $.extend($.TiledImage.prototype, $.EventSource.prototype, /** @lends OpenSeadrag }, /** - * @private * Obtains a tile at the given location. + * @private * @param {Number} x * @param {Number} y * @param {Number} level @@ -1934,8 +1934,8 @@ $.extend($.TiledImage.prototype, $.EventSource.prototype, /** @lends OpenSeadrag }, /** - * @private * Dispatch a job to the ImageLoader to load the Image for a Tile. + * @private * @param {OpenSeadragon.Tile} tile * @param {Number} time */ @@ -1961,8 +1961,8 @@ $.extend($.TiledImage.prototype, $.EventSource.prototype, /** @lends OpenSeadrag }, /** - * @private * Callback fired when a Tile's Image finished downloading. + * @private * @param {OpenSeadragon.Tile} tile * @param {Number} time * @param {*} data image data @@ -2109,9 +2109,9 @@ $.extend($.TiledImage.prototype, $.EventSource.prototype, /** @lends OpenSeadrag /** - * @private * Determines the 'best tiles' from the given 'last best' tiles and the * tile in question. + * @private * * @param {OpenSeadragon.Tile[]} previousBest The best tiles so far. * @param {OpenSeadragon.Tile} tile The new tile to consider. @@ -2131,8 +2131,8 @@ $.extend($.TiledImage.prototype, $.EventSource.prototype, /** @lends OpenSeadrag }, /** - * @private * Sorts tiles in an array according to distance and visibility. + * @private * * @param {OpenSeadragon.Tile[]} tiles The tiles. */ @@ -2154,7 +2154,6 @@ $.extend($.TiledImage.prototype, $.EventSource.prototype, /** @lends OpenSeadrag /** - * @private * Returns true if the given tile provides coverage to lower-level tiles of * lower resolution representing the same content. If neither x nor y is * given, returns true if the entire visible level provides coverage. @@ -2162,6 +2161,7 @@ $.extend($.TiledImage.prototype, $.EventSource.prototype, /** @lends OpenSeadrag * Note that out-of-bounds tiles provide coverage in this sense, since * there's no content that they would need to cover. Tiles at non-existent * levels that are within the image bounds, however, do not. + * @private * * @param {Object} coverage - A '3d' dictionary [level][x][y] --> Boolean. * @param {Number} level - The resolution level of the tile. @@ -2202,10 +2202,10 @@ $.extend($.TiledImage.prototype, $.EventSource.prototype, /** @lends OpenSeadrag }, /** - * @private * Returns true if the given tile is completely covered by higher-level * tiles of higher resolution representing the same content. If neither x * nor y is given, returns true if the entire visible level is covered. + * @private * * @param {Object} coverage - A '3d' dictionary [level][x][y] --> Boolean. * @param {Number} level - The resolution level of the tile. @@ -2227,8 +2227,8 @@ $.extend($.TiledImage.prototype, $.EventSource.prototype, /** @lends OpenSeadrag }, /** - * @private * Sets whether the given tile provides coverage or not. + * @private * * @param {Object} coverage - A '3d' dictionary [level][x][y] --> Boolean. * @param {Number} level - The resolution level of the tile. @@ -2253,10 +2253,10 @@ $.extend($.TiledImage.prototype, $.EventSource.prototype, /** @lends OpenSeadrag }, /** - * @private * Resets coverage information for the given level. This should be called * after every draw routine. Note that at the beginning of the next draw * routine, coverage for every visible tile should be explicitly set. + * @private * * @param {Object} coverage - A '3d' dictionary [level][x][y] --> Boolean. * @param {Number} level - The resolution level of tiles to completely reset. diff --git a/src/viewer.js b/src/viewer.js index f60fcffa..b32d8015 100644 --- a/src/viewer.js +++ b/src/viewer.js @@ -478,7 +478,7 @@ $.Viewer = function( options ) { debugGridColor: this.debugGridColor, options: this.drawerOptions[drawerCandidate], }); - this.drawerOptions.constructor = Drawer; + break; } }