/* * OpenSeadragon - DrawerBase * * Copyright (C) 2009 CodePlex Foundation * Copyright (C) 2010-2023 OpenSeadragon contributors * * 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 CodePlex Foundation nor the names of its * 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( $ ){ $.DrawerOptions = class DrawerOptions{ constructor(options){} }; /** * @class DrawerBase * @memberof OpenSeadragon * @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. */ $.DrawerBase = class DrawerBase{ constructor(options){ $.console.assert( options.viewer, "[Drawer] options.viewer is required" ); //backward compatibility for positional args while preferring more //idiomatic javascript options object as the only argument var args = arguments; if( !$.isPlainObject( options ) ){ options = { source: args[ 0 ], // Reference to Viewer tile source. viewport: args[ 1 ], // Reference to Viewer viewport. element: args[ 2 ] // Parent element. }; } $.console.assert( options.viewport, "[Drawer] options.viewport is required" ); $.console.assert( options.element, "[Drawer] options.element is required" ); if ( options.source ) { $.console.error( "[Drawer] options.source is no longer accepted; use TiledImage instead" ); } this.viewer = options.viewer; this.viewport = options.viewport; 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 ); // TO DO: Does this need to be in DrawerBase, or only in Drawer implementations? // Original commment: // We force our container to ltr because our drawing math doesn't work in rtl. // This issue only affects our canvas renderer, but we do it always for consistency. // Note that this means overlays you want to be rtl need to be explicitly set to rtl. this.container.dir = 'ltr'; // the first time this.canvas is accessed, implementations will create it this.canvas.style.width = "100%"; this.canvas.style.height = "100%"; this.canvas.style.position = "absolute"; $.setElementOpacity( this.canvas, this.viewer.opacity, true ); // set // Allow pointer events to pass through the canvas element so implicit // pointer capture works on touch devices $.setElementPointerEventsNone( this.canvas ); $.setElementTouchActionNone( this.canvas ); // explicit left-align this.container.style.textAlign = "left"; this.container.appendChild( this.canvas ); this._checkForAPIOverrides(); } get isOpenSeadragonDrawer(){ return true; } get canvas(){ if(!this._renderingTarget){ this._renderingTarget = this.createDrawingElement(); } return this._renderingTarget; } get element(){ $.console.error('Drawer.element is deprecated. Use Drawer.container instead.'); return this.container; } /** * @property {String|undefined} type What type of drawer this is. Implementations should override this property. */ get type(){ return undefined; } /** * @returns {Boolean} whether the drawer implementation is supported by the browser */ 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 * @returns {Element} the element to draw into */ createDrawingElement() { $.console.error('Drawer.createDrawingElement must be implemented by child class'); return null; } /** * @param {Array} tiledImages - An array of TiledImages that are ready to be drawn */ draw(tiledImages) { $.console.error('Drawer.draw must be implemented by child class'); } /** * @returns {Boolean} True if rotation is supported. */ canRotate() { $.console.error('Drawer.canRotate must be implemented by child class'); } /** * Destroy the drawer (unload current loaded tiles) */ destroy() { $.console.error('Drawer.destroy must be implemented by child class'); } /** * @returns {Boolean} Whether this drawer requires enforcing minimum tile overlap to avoid showing seams. */ minimumOverlapRequired() { return false; } /** * Turns image smoothing on or off for this viewer. Note: Ignored in some (especially older) browsers that do not support this property. * * @function * @param {Boolean} [imageSmoothingEnabled] - Whether or not the image is * drawn smoothly on the canvas; see imageSmoothingEnabled in * {@link OpenSeadragon.Options} for more explanation. */ setImageSmoothingEnabled(imageSmoothingEnabled){ $.console.error('Drawer.setImageSmoothingEnabled must be implemented by child class'); } /** * Optional public API to draw a rectangle (e.g. for debugging purposes) * Child classes can override this method if they wish to support this * @param {OpenSeadragon.Rect} rect */ drawDebuggingRect(rect) { $.console.warn('[drawer].drawDebuggingRect is not implemented by this drawer'); } // Deprecated functions clear(){ $.console.warn('[drawer].clear() is deprecated. The drawer is responsible for clearing itself as needed before drawing tiles.'); } // Private functions /** * @private * @inner * 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. */ _checkForAPIOverrides(){ if(this.createDrawingElement === $.DrawerBase.prototype.createDrawingElement){ throw("[drawer].createDrawingElement must be implemented by child class"); } if(this.draw === $.DrawerBase.prototype.draw){ throw("[drawer].draw must be implemented by child class"); } if(this.canRotate === $.DrawerBase.prototype.canRotate){ throw("[drawer].canRotate must be implemented by child class"); } if(this.destroy === $.DrawerBase.prototype.destroy){ throw("[drawer].destroy must be implemented by child class"); } if(this.setImageSmoothingEnabled === $.DrawerBase.prototype.setImageSmoothingEnabled){ throw("[drawer].setImageSmoothingEnabled must be implemented by child class"); } } _raiseTileDrawingEvent(tiledImage, context, tile, rendered){ /** * This event is fired just before the tile is drawn giving the application a chance to alter the image. * * NOTE: This event is only fired in certain drawing contexts: either the 'canvas' drawer is * being used, or the 'webgl' drawer with 'drawerOptions.webgl.continuousTileRefresh'. * * @event tile-drawing * @memberof OpenSeadragon.Viewer * @type {object} * @property {OpenSeadragon.Viewer} eventSource - A reference to the Viewer which raised the event. * @property {OpenSeadragon.Tile} tile - The Tile being drawn. * @property {OpenSeadragon.TiledImage} tiledImage - Which TiledImage is being drawn. * @property {CanvasRenderingContext2D} context - The HTML canvas context being drawn into. * @property {CanvasRenderingContext2D} rendered - The HTML canvas context containing the tile imagery. * @property {?Object} userData - Arbitrary subscriber-defined object. */ this.viewer.raiseEvent('tile-drawing', { tiledImage: tiledImage, context: context, tile: tile, rendered: rendered }); } // Utility functions /** * Scale from OpenSeadragon viewer rectangle to drawer rectangle * (ignoring rotation) * @param {OpenSeadragon.Rect} rectangle - The rectangle in viewport coordinate system. * @returns {OpenSeadragon.Rect} Rectangle in drawer coordinate system. */ viewportToDrawerRectangle(rectangle) { var topLeft = this.viewport.pixelFromPointNoRotate(rectangle.getTopLeft(), true); var size = this.viewport.deltaPixelsFromPointsNoRotate(rectangle.getSize(), true); return new $.Rect( topLeft.x * $.pixelDensityRatio, topLeft.y * $.pixelDensityRatio, size.x * $.pixelDensityRatio, size.y * $.pixelDensityRatio ); } /** * This function converts the given point from to the drawer coordinate by * multiplying it with the pixel density. * This function does not take rotation into account, thus assuming provided * point is at 0 degree. * @param {OpenSeadragon.Point} point - the pixel point to convert * @returns {OpenSeadragon.Point} Point in drawer coordinate system. */ viewportCoordToDrawerCoord(point) { var vpPoint = this.viewport.pixelFromPointNoRotate(point, true); return new $.Point( vpPoint.x * $.pixelDensityRatio, vpPoint.y * $.pixelDensityRatio ); } // Internal utility functions /** * @private * @inner * Calculate width and height of the canvas based on viewport dimensions * and pixelDensityRatio * @returns {Dictionary} {x, y} size of the canvas */ _calculateCanvasSize() { var pixelDensityRatio = $.pixelDensityRatio; var viewportSize = this.viewport.getContainerSize(); return { // canvas width and height are integers x: Math.round(viewportSize.x * pixelDensityRatio), y: Math.round(viewportSize.y * pixelDensityRatio) }; } }; }( OpenSeadragon ));