From 92e111d65dd5e3cf53a69e5a16db0c90b0f0bbb3 Mon Sep 17 00:00:00 2001 From: Sergey Marin Date: Sun, 8 Oct 2023 14:34:49 +0300 Subject: [PATCH 1/2] Add type definitions --- package.json | 1 + src/types.d.ts | 1259 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 1260 insertions(+) create mode 100644 src/types.d.ts diff --git a/package.json b/package.json index deca39c85..b2889c230 100644 --- a/package.json +++ b/package.json @@ -5,6 +5,7 @@ "author": "Google Inc.", "license": "Apache-2.0", "main": "src/index.js", + "types": "src/types.d.ts", "homepage": "http://www.marzipano.net", "repository": { "type": "git", diff --git a/src/types.d.ts b/src/types.d.ts new file mode 100644 index 000000000..ba51eb9ff --- /dev/null +++ b/src/types.d.ts @@ -0,0 +1,1259 @@ +declare module 'marzipano' { + /***************** + **** Classes *** + *****************/ + + /** + * ControlComposer + */ + export class ControlComposer {} + + /** + * ControlCursor + */ + export class ControlCursor { + constructor( + controls: Controls, + id: string, + element: HTMLElement, + opts?: ControlCursorOptions + ) + } + + export interface ControlCursorOptions { + /** + * @default 'move' + */ + active?: string + /** + * @default 'default' + */ + inactive?: string + /** + * @default 'default' + */ + disabled?: string + } + + /** + * Controls + */ + export class Controls { + addMethodGroup(groupId: string, methodIds: string): void + + attach(renderLoop: RenderLoop): void + + attached(): boolean + + destroy(): void + + detach(): void + + disable(): void + + disableMethod(id: string): void + + disableMethodGroup(groupId: string): void + + enable(): void + + enabled(): boolean + + enableMethod(id: string): void + + enableMethodGroup(groupId: string): void + + method(id: string): ControlMethod + + methodGroups(): ControlMethod[] + + methods(): ControlMethod[] + + registerMethod(id: string, instance: ControlMethod, enable?: boolean): void + + removeMethodGroup(groupId: string): void + + unregisterMethod(id: string): void + } + + /** + * CubeGeometry + */ + export class CubeGeometry extends Geometry { + constructor(levelPropertiesList: { size: number; tileSize: number }[]) + } + + /** + * CubeTile + */ + export class CubeTile implements Tile { + cmp(that: Tile): number + + equals(that: Tile): boolean + + hash(): number + } + + /** + * DragControlMethod + */ + export class DragControlMethod { + constructor( + element: HTMLElement, + pointerType: string, + opts?: { friction?: number; maxFrictionTime?: number } + ) + } + + /** + * DynamicAsset + */ + export class DynamicAsset extends StaticAsset {} + + /** + * Dynamics + */ + export class Dynamics { + offset: number + velocity: number + friction: number + } + + /** + * ElementPressControlMethod + */ + export class ElementPressControlMethod { + constructor( + element: HTMLElement, + parameter: string, + velocity: number, + friction: number + ) + + destroy(): void + } + + export interface ElementPressControlMethodInterface + extends ElementPressControlMethod {} + + /** + * EquirectGeometry + */ + export class EquirectGeometry extends Geometry { + constructor(levelPropertiesList: { width: number }[]) + + type: 'equirect' + } + + /** + * EquirectTile + */ + export class EquirectTile implements Tile { + cmp(that: Tile): number + + equals(that: Tile): boolean + + hash(): number + } + + /** + * FlatGeometry + */ + export class FlatGeometry extends Geometry { + constructor( + levelPropertiesList: { + width: number + tileWidth: number + height: number + tileHeight: number + }[] + ) + + type: 'flat' + } + + /** + * FlatTile + */ + export abstract class FlatTile implements Tile { + cmp(that: Tile): number + + equals(that: Tile): boolean + + hash(): number + } + + /** + * FlatView + */ + export abstract class FlatView implements View { + constructor(params: FlatViewParams, limiter?: FlatViewLimiter) + + type: 'flat' + + coordinatesToScreen(coords: Coords, result?: Coords): Coords + + limiter(): null | FlatViewLimiter + + mediaAspectRatio(): number + + offsetX(xOffset: number): void + + offsetY(xOffset: number): void + + offsetZoom(zoomOffset: number): void + + parameters(opts?: FlatViewParams): FlatViewParams + + screenToCoordinates(coords: Coords, result?: Coords): Coords + + setLimiter(limiter: FlatViewLimiter): void + + setMediaAspectRatio(mediaAspectRatio: number): void + + setParameters(params: FlatViewParams): void + + setX(x: number): void + + setY(y: number): void + + setZoom(zoom: number): void + + x(): number + + y(): number + + zoom(): number + + destroy(): void + + height(): number + + intersects(rectangle: [number, number][]): boolean + + inverseProjection(): Array + + projection(): [number, number, number, number] + + selectLevel(levelList: number[]): number + + setSize(size: Size): void + + size(size?: Size): Size + + width(): number + + pitch(): number + + yaw(): number + } + + interface FlatViewParams extends Coords { + zoom?: number + mediaAspectRation: number + } + + type FlatViewLimiter = (params: FlatViewParams) => FlatViewParams + + /** + * HammerGestures + */ + export abstract class HammerGestures {} + + /** + * Hotspot + */ + export abstract class Hotspot { + constructor( + domElement: HTMLElement, + view: View, + coords: RectilinearCoords, + opts: HotspotOptions + ) + + destroy(): void + + domElement(): HTMLElement + + perspective(): Perspective + + position(): RectilinearCoords + + setPerspective(perspective: Perspective): void + + setPosition(coords: RectilinearCoords): void + + show(): void + } + + export interface HotspotOptions { + perspective?: Perspective + } + + /** + * HotspotContainer + */ + export class HotspotContainer { + constructor( + parentDomElement: HTMLElement, + stage: Stage, + view: View, + renderLoop: RenderLoop, + opts?: { rect?: RectSpec } + ) + + createHotspot( + domElement: HTMLElement, + coords?: RectilinearCoords, + opts?: HotspotOptions + ): Hotspot + + destroy(): void + + destroyHotspot(hotspot: Hotspot): void + + domElement(): HTMLElement + + hasHotspot(hotspot: Hotspot): boolean + + hide(): void + + listHotspots(): Hotspot[] + + rect(): Rect + + setRect(rect: Rect): void + + show(): void + } + + /** + * HtmlImageLoader + */ + export class HtmlImageLoader { + constructor(stage: Stage) + + loadImage(url: string, rect?: Rect, done?: Function) + } + + export interface HtmlImageLoaderInteface extends HtmlImageLoader {} + + /** + * ImageUrlSource + */ + export class ImageUrlSource implements Source { + constructor( + sourceFromTile: (tile: Tile) => { url: string; rect?: Rect }, + opts?: { concurrency?: number; retryDelay?: number } + ) + + static fromString: ( + url: string, + options?: { + cubeMapPreviewFaceOrder?: string + cubeMapPreviewUrl?: string + retryDelay?: number + } + ) => ImageUrlSource + + loadAsset(stage: Stage, tile: Tile, done: Function): Function + + addEventListener(event: Event, callback: Function) + + removeEventListener(event: Event, callback: Function) + } + + /** + * KeyControlMethod + */ + export class KeyControlMethod { + constructor( + keyCode: number, + parameter: string, + velocity: number, + friction: number, + element?: HTMLElement + ) + + destroy(): void + } + + /** + * Layer + */ + export class Layer { + constructor( + source: Source, + geometry: Geometry, + view: View, + textureStore: TextureStore, + opts?: LayerOptions + ) + + destroy(): void + + effects(): Effects + + fixedLevel(): number | null + + geometry(): Geometry + + mergeEffects(effects: Effects): void + + pinFirstLevel(): void + + setEffects(effects: Effects): void + + setFixedLevel(levelIndex: number | null): void + + source(): Source + + textureStore(): TextureStore + + unpinFirstLevel(): void + + unpinLevel(levelIndex: number | null): void + + view(): View + + addEventListener(event: Event, callback: Function) + + removeEventListener(event: Event, callback: Function) + } + + export interface LayerInteface extends Layer {} + + interface LayerOptions { + effects?: Effects + } + + /** + * NetworkError + */ + export class NetworkError {} + + /** + * PinchZoomControlMethod + */ + export class PinchZoomControlMethod { + constructor(element: HTMLElement, pointerType: string, opts: any) + } + + export interface PinchZoomControlMethodInterface + extends PinchZoomControlMethod {} + + /** + * PinchZoomControlMethod + */ + export class QtvrControlMethod { + constructor( + element: HTMLElement, + pointerType: string, + opts: { speed?: number; friction?: number; maxFrictionTime?: number } + ) + + destroy(): void + } + + /** + * RectilinearView + */ + export class RectilinearView implements View { + constructor( + params?: RectilinearViewParams, + limiter?: RectilinearViewLimiter + ) + + destroy(): void + + height(): number + + intersects(rectangle: [number, number][]): boolean + + inverseProjection(): number[] + + projection(): [number, number, number, number] + + selectLevel(levelList: number[]): number + + size(size?: Size): Size + + setSize(size: Size): void + + width(): number + + type: 'rectilinear' + + coordinatesToPerspectiveTransform( + coords: RectilinearCoords, + radius: number, + extraTransforms: string + ): string + + coordinatesToScreen(coords: Coords, result?: Coords): Coords + + fov(): number + + limiter(): null | RectilinearViewLimiter + + normalizeToClosest( + coords: RectilinearCoords, + result?: RectilinearCoords + ): void + + offsetFov(fovOffset: number): void + + offsetPitch(pitchOffset: number): void + + offsetRoll(rollOffset: number): void + + offsetYaw(yawOffset: number): void + + parameters(opts?: RectilinearViewParams): RectilinearViewParams + + pitch(): number + + screenToCoordinates( + coords: Coords, + opts?: RectilinearCoords + ): RectilinearCoords + + setFov(fov: number): void + + setLimiter(limiter: RectilinearViewLimiter): void + + setPitch(pitch: number): void + + setYaw(yaw: number): void + + setRoll(roll: number): void + + yaw(): number + + roll(): number + + setParameters(params: RectilinearViewParams): void + + static limit: Limit + } + + class Limit { + hfov(min: number, max: number): RectilinearViewLimiter + + pitch(min: number, max: number): RectilinearViewLimiter + + resolution(size: number): RectilinearViewLimiter + + roll(min: number, max: number): RectilinearViewLimiter + + traditional( + maxResolution: number, + maxVFov: number, + maxHFov?: number + ): RectilinearViewLimiter + + vfov(min: number, max: number): RectilinearViewLimiter + + yaw(min: number, max: number): RectilinearViewLimiter + } + + export interface RectilinearViewParams extends RectilinearCoords { + roll?: number + fov?: number + } + + export type RectilinearViewLimiter = ( + params: RectilinearViewParams + ) => RectilinearViewParams + + /** + * RendererRegistry + */ + export class RendererRegistry { + get(geometryType: string, viewType: String, renderer: Renderer): void + + set(geometryType: string, viewType: String, renderer: Renderer): void + } + + /** + * RenderLoop + */ + export class RenderLoop { + constructor(stage: Stage) + + destroy(): void + + renderOnNextFrame(): void + + stage(): Stage + + start(): void + + stop(): void + } + + /** + * Scene + */ + export class Scene { + constructor(viewer: Viewer, view: View) + + createLayer(opts?: { + source: Source + geometry: Geometry + pinFirstLevel?: boolean + textureStoreOpts?: TextureStoreOptions + layerOpts?: LayerOptions + }): Layer + + destroy(): void + + destroyAllLayers(): void + + destroyLayer(layer: Layer): void + + hotspotContainer(): HotspotContainer + + layer(): Layer + + viewer(): Viewer + + listLayers(): Layer[] + + lookTo(params: LookToParams, opts?: LookToOptions, done?: Function): void + + movement(): Function + + startMovement(fn: Function, done?: Function): void + + stopMovement(): void + + switchTo(opts?: SwitchSceneOptions, done?: Function): void + + view(): View + + viewer(): Viewer + + visibled(): boolean + + addEventListener(event: Event, callback: Function) + removeEventListener(event: Event, callback: Function) + } + + /** + * ScrollZoomControlMethod + */ + export class ScrollZoomControlMethod { + constructor( + element?: HTMLElement, + opts?: { fictionTime?: number; zoomDelta?: number } + ) + + destroy(): void + } + + export interface ScrollZoomControlMethodInterface + extends ScrollZoomControlMethod {} + + /** + * SingleAssetSource + */ + export class SingleAssetSource { + constructor(asset: Asset) + + loadAsset(stage: Stage, tile: Tile, done?: Function): void + } + + /** + * StaticAsset + */ + export class StaticAsset implements Asset { + constructor(element: HTMLElement) + + element(): HTMLElement + + height(): number + + isDynamic(): false + + timestamp(): number + + width(): number + } + + /** + * TextureStore + */ + export class TextureStore { + constructor(source: Source, stage: Stage, opts?: TextureStoreOptions) + + clear(): void + + clearNotPinned(): void + + destroy(): void + + endFrame(): void + + markTile(tile: Tile): void + + pin(tile: Tile): number + + query(tile: Tile): any + + source(): Source + + stage(): Stage + + startFrame(): void + + unpin(tile: Tile): number + } + + export interface TextureStoreOptions { + previouslyVisibleCacheSize?: number + } + + /** + * TextureStore + */ + export class TextureStoreItem { + constructor(store: TextureStore, tile: Tile) + } + + /** + * TileSearcher + */ + export class TileSearcher { + search(view: View, tile: Tile, result: Tile[]): number + } + + /** + * Timer + */ + export class Timer { + constructor(opts?: { duration?: number }) + + duration(): number + + start(): number + + started(): boolean + + stop(): boolean + } + + /** + * VelocityControlMethod + */ + export class VelocityControlMethod { + constructor(parameter: string) + + destroy(): boolean + + setFriction(friction: number): void + + setVelocity(velocity: number): void + } + + export interface VelocityControlMethodInterface + extends VelocityControlMethod {} + + /** + * VelocityControlMethod + */ + export class Viewer { + constructor(domElement: HTMLElement, opts?: ViewerOptions) + + breakIdleMovement(): void + + controls(): Controls + + createEmptyScene(opts: { view: View }): Scene + + createScene(opts: CreateSceneOptions): Scene + + destroy(): void + + destroyAllScenes(): void + + destroyScene(scene: Scene): void + + domElement(): HTMLElement + + hasScene(scene: Scene): boolean + + listScenes(): Scene[] + + lookTo(opts?: LookToOptions, done?: Function): void + + movement(): Function + + renderLoop(): RenderLoop + + scene(): Scene + stage(): Stage + + setIdleMovement(timeout: number, movement?: Function): void + + startMovement(fn: Function, done?: Function): void + + stopMovement(): void + + switchScene( + newScene: Scene, + opts?: SwitchSceneOptions, + done?: Function + ): void + + updateSize(): void + + view(): View + } + + export interface VelocityControlMethodInterface + extends VelocityControlMethod {} + + export interface ViewerOptions { + controls?: any + stage?: Stage + cursors?: { + drag?: ControlCursorOptions + } + } + + export interface CreateSceneOptions { + view: View + source: Source + geometry: Geometry + pinFirstLevel?: boolean + textureStoreOpts?: TextureStoreOptions + layerOpts?: LayerOptions + } + + /** + * WebGlCubeRenderer + */ + export class WebGlCubeRenderer implements Renderer {} + + /** + * WebGlEquirectRenderer + */ + export class WebGlEquirectRenderer implements Renderer { + endLayer(layer: Layer, rect: Rect): void + + renderTile(tile: Tile, texture: any, layer: Layer, layerZ: number): void + + startLayer(layer: Layer, rect: Rect): void + } + + export interface WebGlEquirectRendererInterface + extends WebGlEquirectRenderer {} + + /** + * WebGlFlatRenderer + */ + export class WebGlFlatRenderer implements Renderer {} + + /** + * WebGlStage + */ + export class WebGlStage implements Stage { + constructor(opts: { + antialias?: boolean + preserveDrawingBuffer?: boolean + generateMipmaps?: boolean + wrapContext?: boolean + }) + + addLayer(layer: Layer, i?: number): void + + createTexture(tile: Tile, asset: Asset, done?: Function): void + + destroy(): void + + domElement(): HTMLElement + + endFrame(): void + + hasLayer(layer: Layer): boolean + + height(): number + + listLayers(): Layer[] + + loadImage(url: string, rect?: Rect, done?: Function): void + + moveLayer(layer: Layer, i: number) + + registerRenderer(geometryType: string, viewType: string, Renderer: any) + + removeAllLayers(): void + + removeLayer(layer: Layer): void + + render(): void + + setSize(size: Size): void + + setSizeForType(size): void + + size(size?: Size): Size + + startFrame(): void + + validateLayer(layer: Layer): void + + width(): number + + addEventListener(event: Event, callback: Function) + + removeEventListener(event: Event, callback: Function) + } + + export interface WebGlStageStage extends WebGlStage {} + + /*************************** + **** Generic Interfaces *** + ***************************/ + + /** + * Renderer + */ + export type Renderer = any + + /** + * ControlMethod + */ + export type ControlMethod = any + + /** + * Coords + */ + export interface Coords { + x: number + y: number + } + + /** + * Geometry + */ + export abstract class Geometry { + type: 'cube' | 'equirect' | 'flat' + + visibleTiles(view: View, level: any): Tile[] + } + + /** + * Perspective + */ + export interface Perspective { + radius?: number + extraTransforms: string + } + + /** + * Rect + */ + export interface Rect extends Coords, Size {} + + /** + * Source + */ + export interface Source { + loadAsset(stage: Stage, tile: Tile, done: Function): Function + addEventListener(event: Event, callback: Function) + removeEventListener(event: Event, callback: Function) + } + + /** + * Effects + */ + export interface Effects { + opacity?: number + rect?: RectSpec + colorOffset?: any + colorMatrix?: any + textureCrop?: Rect + } + + /** + * RectSpec + */ + interface RectSpec { + relativeX: number + relativeY: number + relativeWidth: number + relativeHeight: number + absoluteX: number + absoluteY: number + absoluteWidth: number + absoluteHeight: number + } + + /** + * LookTo + */ + type LookToParams = RectilinearCoords | RectilinearCoords + + interface LookToOptions { + ease?: Function + controlsInterrups?: number + transitionDuration?: number + closest?: number + } + + /** + * Switch Scene + */ + interface SwitchSceneOptions { + transitionDuration?: number + transitionUpdate?: number, + wait?: boolean, + progress?: ( value: number ) => void + } + + /** + * RectilinearCoords + */ + interface RectilinearCoords { + yaw: number + pitch: number + } + + /** + * Size + */ + interface Size { + width: number + height: number + } + + /** + * View + */ + export interface View { + type: 'rectilinear' | 'flat' + + destroy(): void + + height(): number + + intersects(rectangle: [number, number][]): boolean + + inverseProjection(): Array + + projection(): [number, number, number, number] + + selectLevel(levelList: number[]): number + + size(size?: Size): Size + + setSize(size: Size): void + + width(): number + + pitch(): number + + yaw(): number + } + + /** + * Tile + */ + interface Tile { + cmp(that): number + + equals(that): boolean + + hash(): number + } + + /** + * Stage + */ + export interface Stage { + addLayer(layer: Layer, i?: number): void + + createTexture(tile: Tile, asset: Asset, done?: Function): void + + destroy(): void + + domElement(): HTMLElement + + endFrame(): void + + hasLayer(layer: Layer): boolean + + height(): number + + listLayers(): Layer[] + + loadImage(url: string, rect?: Rect, done?: Function): void + + moveLayer(layer: Layer, i: number) + + registerRenderer(geometryType: string, viewType: string, Renderer: any) + + removeAllLayers(): void + + removeLayer(layer: Layer): void + + render(): void + + setSize(size: Size): void + + /** + * + * @deprecated Call Stage#setSize instead + */ + setSizeForType(size): void + + size(size?: Size): Size + + startFrame(): void + + validateLayer(layer: Layer): void + + width(): number + + addEventListener(event: Event, callback: Function) + removeEventListener(event: Event, callback: Function) + } + + /** + * Asset + */ + export interface Asset { + element(): any + + height(): number + + isDynamic(): boolean + + timestamp(): number + + width(): number + } + + /** + * Events + */ + enum Event { + active, + inactive, + parameterDynamics, + hotspotsChange, + afterRender, + beforeRender, + layerChange, + networkError, + textureCancel, + textureError, + textureInvalid, + textureLoad, + textureStartLoad, + textureUnload, + timeout, + change, + resize, + sceneChange, + viewChange, + renderComplete, + renderInvalid, + } + + /** + * Global + */ + export interface autorotateOptions { + /** + * @default 0.1 + */ + yawSpeed?: number + /** + * @default 0.1 + */ + pitchSpeed?: number + /** + * @default 0.1 + */ + fovSpeed?: number + /** + * @default 0.01 + */ + yawAccel?: number + /** + * @default 0.01 + */ + pitchAccel?: number + /** + * @default 0.01 + */ + fovAccel?: number + /** + * @default 0 + */ + targetPitch?: number + targetFov?: number + } + + export function autorotate(options: autorotateOptions): Function + + export type Dependencies = { + eventEmitter: (method: Function) => {} + } + export const dependencies: Dependencies + + export const util: { + async( fn: Function ) : Function; + cancelize( fn: Function ) : Function; + chain( ...fns: Function[] ) : Function; + clamp( value: number, min: number, max: number ) : number; + clearOwnProperties( obj: object ) : void; + cmp( x: any, y: any ) : number; + compose( ...fns: Function[] ) : Function; + convertFov: { + convert( fov: number, fromDimension: number, toDimension: number ) : number; + htov( fov: number, width: number, height: number ) : number; + htod( fov: number, width: number, height: number ) : number; + vtoh( fov: number, width: number, height: number ) : number; + vtod( fov: number, width: number, height: number ) : number; + dtoh( fov: number, width: number, height: number ) : number; + dtov( fov: number, width: number, height: number ) : number; + }; + decimal( x: number ) : number; + defaults( obj: object, defaultsObj: object ) : object; + defer( fn: Function, args: any[] ) : void; + degToRad( deg: number ) : number; + delay( ms: number, done: Function ) : Function; + dom: { + prefixProperty( property: string ) : string; + getWithVendorPrefix( property: string ) : ( element: HTMLElement ) => string; + setWithVendorPrefix( property: string ) : ( element: HTMLElement, val: string ) => string; + setNullTransform( element: HTMLElement ) : void; + setNullTransformOrigin( element: HTMLElement ) : void; + setAbsolute( element: HTMLElement ) : void; + setPixelPosition( element: HTMLElement, x: number, y: number ) : void; + setPixelSize( element: HTMLElement, width: number, height: number ) : void; + setNullSize( element: HTMLElement ) : void; + setFullSize( element: HTMLElement ) : void; + setOverflowHidden( element: HTMLElement ) : void; + setOverflowVisible( element: HTMLElement ) : void; + setNoPointerEvents( element: HTMLElement ) : void; + }; + extend( obj: object, sourceObj: object ) : object; + hash( ...values: number[] ) : number; + inherits( ctor: Function, superCtor: Function ) : void; + mod( a: number, b: number ) : number; + noop() : void; + now() : number; + once( fn: Function ) : Function; + pixelRatio() : number; + radToDeg( rad: number ) : number; + real( x: number ) : number; + retry( fn: Function ) : Function; + tween( duration: number, update: Function, done: Function ) : Function; + type( any ) : string; + } +} \ No newline at end of file From 89c3629cfeed17340889035ff73db15bb1925dd5 Mon Sep 17 00:00:00 2001 From: Sergey Marin Date: Sun, 8 Oct 2023 14:35:18 +0300 Subject: [PATCH 2/2] 0.10.3 --- CHANGELOG | 4 ++++ package.json | 2 +- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/CHANGELOG b/CHANGELOG index 13e4261bc..c1989754b 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -14,6 +14,10 @@ Related GitHub issue or pull request numbers are indicated in brackets. # Upcoming release +# v0.10.3 [2023-10-08] + +# New: add typescript definitions + # v0.10.2 [2021-03-18] # New: implement a pinch drag mode. diff --git a/package.json b/package.json index b2889c230..ce361463a 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "marzipano", - "version": "0.10.2", + "version": "0.10.3", "description": "A 360° media viewer for the modern web", "author": "Google Inc.", "license": "Apache-2.0",