mirror/openseadragon
1
0
Fork 0
mirror of https://github.com/openseadragon/openseadragon.git synced 2024-11-21 12:46:09 +03:00
Code Issues Projects Releases Wiki Activity

fixing jsdocs

Browse Source
This commit is contained in:
Tom 2023-12-18 17:01:17 -05:00
parent 9616e26dd2
commit d5a3cabf13
8 changed files with 129 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
src/drawerbase.js
View File

@ -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() {

7
src/htmldrawer.js
View File

@ -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})

4
src/imageloader.js
View File

@ -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;

97
src/matrix.js
View File

@ -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 ));

23
src/openseadragon.js
View File

@ -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: {

2
src/referencestrip.js
View File

@ -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

24
src/tiledimage.js
View File

@ -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.

2
src/viewer.js
View File

@ -478,7 +478,7 @@ $.Viewer = function( options ) {
debugGridColor: this.debugGridColor,
options: this.drawerOptions[drawerCandidate],
});
this.drawerOptions.constructor = Drawer;
break;
}
}