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

Merge pull request #2466 from pearcetm/fix-docs

Browse Source 
fix jsdoc formatting for drawer classes
This commit is contained in:
Ian Gilman 2024-02-02 09:26:43 -08:00 committed by GitHub
commit e3c3634266
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
4 changed files with 110 additions and 61 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
src/canvasdrawer.js
View File

@ -34,9 +34,10 @@
(function( $ ){
const OpenSeadragon = $; // (re)alias back to OpenSeadragon for JSDoc
/**
* @class CanvasDrawer
* @memberof OpenSeadragon
* @class OpenSeadragon.CanvasDrawer
* @extends OpenSeadragon.DrawerBase
* @classdesc Default implementation of CanvasDrawer for an {@link OpenSeadragon.Viewer}.
* @param {Object} options - Options for this Drawer.
* @param {OpenSeadragon.Viewer} options.viewer - The Viewer that owns this Drawer.
@ -45,14 +46,28 @@
* @param {Number} [options.debugGridColor] - See debugGridColor in {@link OpenSeadragon.Options} for details.
*/
class CanvasDrawer extends $.DrawerBase{
class CanvasDrawer extends OpenSeadragon.DrawerBase{
constructor(options){
super(options);
/**
* The HTML element (canvas) that this drawer uses for drawing
* @member {Element} canvas
* @memberof OpenSeadragon.CanvasDrawer#
*/
/**
* The parent element of this Drawer instance, passed in when the Drawer was created.
* The parent of {@link OpenSeadragon.WebGLDrawer#canvas}.
* @member {Element} container
* @memberof OpenSeadragon.CanvasDrawer#
*/
/**
* 2d drawing context for {@link OpenSeadragon.CanvasDrawer#canvas}.
* @member {Object} context
* @memberof OpenSeadragon.CanvasDrawer#
* @private
*/
this.context = this.canvas.getContext( '2d' );

36
src/drawerbase.js
View File

@ -34,17 +34,18 @@
(function( $ ){
const OpenSeadragon = $; // (re)alias back to OpenSeadragon for JSDoc
/**
* @class DrawerBase
* @memberof OpenSeadragon
* @class OpenSeadragon.DrawerBase
* @classdesc Base class for Drawers that handle rendering of tiles for an {@link OpenSeadragon.Viewer}.
* @param {Object} options - Options for this Drawer.
* @param {OpenSeadragon.Viewer} options.viewer - The Viewer that owns this Drawer.
* @param {OpenSeadragon.Viewport} options.viewport - Reference to Viewer viewport.
* @param {Element} options.element - Parent element.
* @param {HTMLElement} options.element - Parent element.
* @abstract
*/
$.DrawerBase = class DrawerBase{
OpenSeadragon.DrawerBase = class DrawerBase{
constructor(options){
$.console.assert( options.viewer, "[Drawer] options.viewer is required" );
$.console.assert( options.viewport, "[Drawer] options.viewport is required" );
@ -55,12 +56,6 @@ $.DrawerBase = class DrawerBase{
this.debugGridColor = typeof options.debugGridColor === 'string' ? [options.debugGridColor] : options.debugGridColor || $.DEFAULT_SETTINGS.debugGridColor;
this.options = options.options || {};
/**
* The parent element of this Drawer instance, passed in when the Drawer was created.
* The parent of {@link OpenSeadragon.DrawerBase#canvas}.
* @member {Element} container
* @memberof OpenSeadragon.DrawerBase#
*/
this.container = $.getElement( options.element );
this._renderingTarget = this._createDrawingElement();
@ -95,7 +90,8 @@ $.DrawerBase = class DrawerBase{
}
/**
* @returns {String|undefined} What type of drawer this is.
* @abstract
* @returns {String | undefined} What type of drawer this is. Must be overridden by extending classes.
*/
getType(){
$.console.error('Drawer.getType must be implemented by child class');
@ -103,15 +99,17 @@ $.DrawerBase = class DrawerBase{
}
/**
* @returns {Boolean} whether the drawer implementation is supported by the browser
* @abstract
* @returns {Boolean} Whether the drawer implementation is supported by the browser. Must be overridden by extending classes.
*/
static isSupported() {
$.console.error('Drawer.isSupported must be implemented by child class');
}
/**
* create the HTML element (e.g. canvas, div) that the image will be drawn into
* @abstract
* @returns {Element} the element to draw into
* @private
*/
_createDrawingElement() {
$.console.error('Drawer._createDrawingElement must be implemented by child class');
@ -119,13 +117,16 @@ $.DrawerBase = class DrawerBase{
}
/**
* @param {Array} tiledImages - An array of TiledImages that are ready to be drawn
* @abstract
* @param {Array} tiledImages - An array of TiledImages that are ready to be drawn.
* @private
*/
draw(tiledImages) {
$.console.error('Drawer.draw must be implemented by child class');
}
/**
* @abstract
* @returns {Boolean} True if rotation is supported.
*/
canRotate() {
@ -133,7 +134,7 @@ $.DrawerBase = class DrawerBase{
}
/**
* Destroy the drawer (unload current loaded tiles)
* @abstract
*/
destroy() {
$.console.error('Drawer.destroy must be implemented by child class');
@ -141,6 +142,7 @@ $.DrawerBase = class DrawerBase{
/**
* @returns {Boolean} Whether this drawer requires enforcing minimum tile overlap to avoid showing seams.
* @private
*/
minimumOverlapRequired() {
return false;
@ -148,9 +150,7 @@ $.DrawerBase = class DrawerBase{
/**
* Turns image smoothing on or off for this viewer. Note: Ignored in some (especially older) browsers that do not support this property.
*
* @function
* @abstract
* @param {Boolean} [imageSmoothingEnabled] - Whether or not the image is
* drawn smoothly on the canvas; see imageSmoothingEnabled in
* {@link OpenSeadragon.Options} for more explanation.

29
src/htmldrawer.js
View File

@ -34,9 +34,11 @@
(function( $ ){
const OpenSeadragon = $; // alias back for JSDoc
/**
* @class HTMLDrawer
* @memberof OpenSeadragon
* @class OpenSeadragon.HTMLDrawer
* @extends OpenSeadragon.DrawerBase
* @classdesc HTML-based implementation of DrawerBase for an {@link OpenSeadragon.Viewer}.
* @param {Object} options - Options for this Drawer.
* @param {OpenSeadragon.Viewer} options.viewer - The Viewer that owns this Drawer.
@ -45,10 +47,23 @@
* @param {Number} [options.debugGridColor] - See debugGridColor in {@link OpenSeadragon.Options} for details.
*/
class HTMLDrawer extends $.DrawerBase{
class HTMLDrawer extends OpenSeadragon.DrawerBase{
constructor(options){
super(options);
/**
* The HTML element (div) that this drawer uses for drawing
* @member {Element} canvas
* @memberof OpenSeadragon.HTMLDrawer#
*/
/**
* The parent element of this Drawer instance, passed in when the Drawer was created.
* The parent of {@link OpenSeadragon.WebGLDrawer#canvas}.
* @member {Element} container
* @memberof OpenSeadragon.HTMLDrawer#
*/
// Reject listening for the tile-drawing event, which this drawer does not fire
this.viewer.rejectEventHandler("tile-drawing", "The HTMLDrawer does not raise the tile-drawing event");
// Since the tile-drawn event is fired by this drawer, make sure handlers can be added for it
@ -62,6 +77,10 @@ class HTMLDrawer extends $.DrawerBase{
return true;
}
/**
*
* @returns 'html'
*/
getType(){
return 'html';
}
@ -111,9 +130,7 @@ class HTMLDrawer extends $.DrawerBase{
}
/**
* Turns image smoothing on or off for this viewer. Note: Ignored by HTML Drawer
*
* @function
* This function is ignored by the HTML Drawer. Implementing it is required by DrawerBase.
* @param {Boolean} [imageSmoothingEnabled] - Whether or not the image is
* drawn smoothly on the canvas; see imageSmoothingEnabled in
* {@link OpenSeadragon.Options} for more explanation.

85
src/webgldrawer.js
View File

@ -35,9 +35,10 @@
(function( $ ){
const OpenSeadragon = $; // alias for JSDoc
/**
* @class WebGLDrawer
* @memberof OpenSeadragon
* @class OpenSeadragon.WebGLDrawer
* @classdesc Default implementation of WebGLDrawer for an {@link OpenSeadragon.Viewer}. The WebGLDrawer
* loads tile data as textures to the graphics card as soon as it is available (via the tile-ready event),
* and unloads the data (via the image-unloaded event). The drawer utilizes a context-dependent two pass drawing pipeline.
@ -56,43 +57,55 @@
* @param {Number} [options.debugGridColor] - See debugGridColor in {@link OpenSeadragon.Options} for details.
*/
$.WebGLDrawer = class WebGLDrawer extends OpenSeadragon.DrawerBase{
OpenSeadragon.WebGLDrawer = class WebGLDrawer extends OpenSeadragon.DrawerBase{
constructor(options){
super(options);
this.destroyed = false;
// private members
/**
* The HTML element (canvas) that this drawer uses for drawing
* @member {Element} canvas
* @memberof OpenSeadragon.WebGLDrawer#
*/
this._TextureMap = new Map();
this._TileMap = new Map();
/**
* The parent element of this Drawer instance, passed in when the Drawer was created.
* The parent of {@link OpenSeadragon.WebGLDrawer#canvas}.
* @member {Element} container
* @memberof OpenSeadragon.WebGLDrawer#
*/
this._gl = null;
this._firstPass = null;
this._secondPass = null;
this._glFrameBuffer = null;
this._renderToTexture = null;
this._glFramebufferToCanvasTransform = null;
this._outputCanvas = null;
this._outputContext = null;
this._clippingCanvas = null;
this._clippingContext = null;
this._renderingCanvas = null;
// private members
this._destroyed = false;
this._TextureMap = new Map();
this._TileMap = new Map();
// Add listeners for events that require modifying the scene or camera
this.viewer.addHandler("tile-ready", ev => this._tileReadyHandler(ev));
this.viewer.addHandler("image-unloaded", ev => this._imageUnloadedHandler(ev));
this._gl = null;
this._firstPass = null;
this._secondPass = null;
this._glFrameBuffer = null;
this._renderToTexture = null;
this._glFramebufferToCanvasTransform = null;
this._outputCanvas = null;
this._outputContext = null;
this._clippingCanvas = null;
this._clippingContext = null;
this._renderingCanvas = null;
// Reject listening for the tile-drawing and tile-drawn events, which this drawer does not fire
this.viewer.rejectEventHandler("tile-drawn", "The WebGLDrawer does not raise the tile-drawn event");
this.viewer.rejectEventHandler("tile-drawing", "The WebGLDrawer does not raise the tile-drawing event");
// Add listeners for events that require modifying the scene or camera
this.viewer.addHandler("tile-ready", ev => this._tileReadyHandler(ev));
this.viewer.addHandler("image-unloaded", ev => this._imageUnloadedHandler(ev));
// this.viewer and this.canvas are part of the public DrawerBase API
// and are defined by the parent DrawerBase class. Additional setup is done by
// the private _setupCanvases and _setupRenderer functions.
this._setupCanvases();
this._setupRenderer();
// Reject listening for the tile-drawing and tile-drawn events, which this drawer does not fire
this.viewer.rejectEventHandler("tile-drawn", "The WebGLDrawer does not raise the tile-drawn event");
this.viewer.rejectEventHandler("tile-drawing", "The WebGLDrawer does not raise the tile-drawing event");
this.context = this._outputContext; // API required by tests
// this.viewer and this.canvas are part of the public DrawerBase API
// and are defined by the parent DrawerBase class. Additional setup is done by
// the private _setupCanvases and _setupRenderer functions.
this._setupCanvases();
this._setupRenderer();
this.context = this._outputContext; // API required by tests
}
@ -101,7 +114,7 @@
* Clean up the renderer, removing all resources
*/
destroy(){
if(this.destroyed){
if(this._destroyed){
return;
}
// clear all resources used by the renderer, geometries, textures etc
@ -145,13 +158,13 @@
this._gl = null;
// set our destroyed flag to true
this.destroyed = true;
this._destroyed = true;
}
// Public API required by all Drawer implementations
/**
*
* @returns {Boolean} true if the drawer supports rotation
* @returns {Boolean} true
*/
canRotate(){
return true;
@ -172,6 +185,10 @@
return !!( webglContext );
}
/**
*
* @returns 'webgl'
*/
getType(){
return 'webgl';
}
@ -393,7 +410,7 @@
// Public API required by all Drawer implementations
/**
* Set the context2d imageSmoothingEnabled parameter
* Required by DrawerBase, but has no effect on WebGLDrawer.
* @param {Boolean} enabled
*/
setImageSmoothingEnabled(enabled){