diff --git a/src/three/plugins/API.md b/src/three/plugins/API.md index 2c9cb4bba..ad44bc574 100644 --- a/src/three/plugins/API.md +++ b/src/three/plugins/API.md @@ -12,7 +12,12 @@ Abstract base class for `LoadRegionPlugin` regions. Subclass and override ```js constructor( { + // Geometric error target used when this region controls + // refinement. errorTarget = 10: number, + + // When `true`, tiles outside this region are suppressed (mask + // mode). mask = false: boolean, } ) @@ -30,8 +35,14 @@ An oriented bounding-box load region. Only tiles that intersect `obb` are loaded ```js constructor( { + // The oriented bounding box; defaults to an empty OBB at the + // origin. obb?: OBB, + + // Geometric error target for tiles inside the region. errorTarget = 10: number, + + // Mask mode — suppresses tiles outside this region. mask = false: boolean, } ) @@ -49,8 +60,13 @@ A ray-based load region. Only tiles that intersect `ray` are loaded. ```js constructor( { + // The ray; defaults to a ray at the origin pointing in +Z. ray?: Ray, + + // Geometric error target for tiles inside the region. errorTarget = 10: number, + + // Mask mode — suppresses tiles outside this region. mask = false: boolean, } ) @@ -68,8 +84,14 @@ A spherical load region. Only tiles that intersect `sphere` are loaded. ```js constructor( { + // The sphere volume; defaults to an empty sphere at the + // origin. sphere?: Sphere, + + // Geometric error target for tiles inside the region. errorTarget = 10: number, + + // Mask mode — suppresses tiles outside this region. mask = false: boolean, } ) @@ -93,14 +115,35 @@ required. Requires Three.js r170 or later. ```js constructor( { + // The renderer used to generate a `WebGLArrayRenderTarget`. renderer: WebGLRenderer, + + // Initial number of instances in the batched mesh. instanceCount = 500: number, + + // Minimum vertex space to reserve per tile geometry added. vertexCount = 1000: number, + + // Minimum index space to reserve per tile geometry added. indexCount = 1000: number, + + // Fraction by which to grow the mesh when capacity is + // exceeded. expandPercent = 0.25: number, + + // Hard cap on instance count (clamped to GPU limits). maxInstanceCount = Infinity: number, + + // Free the original tile scene after batching. Set to `false` + // when used with `UnloadTilesPlugin`. discardOriginalContent = true: boolean, + + // Override width/height for the texture array; defaults to the + // first tile's texture size. textureSize = null: number | null, + + // Custom material for the batched mesh; defaults to the first + // tile's material type. material = null: Material | null, } ) @@ -121,10 +164,21 @@ instead. ```js constructor( { + // Cesium Ion API token. apiToken?: string, + + // Cesium Ion asset ID, or `null` when using an explicit root + // URL. assetId = null: string | null, + + // Automatically refresh the token on 4xx errors. autoRefreshToken = false: boolean, + + // Apply recommended renderer settings for Cesium Ion assets. useRecommendedSettings = true: boolean, + + // Callback `(type, tiles, asset)` invoked for non-3DTILES + // asset types. assetTypeHandler?: function, } ) @@ -141,11 +195,27 @@ fetch, lock, and release overlay textures. ```js constructor( { + // Opacity of the overlay layer (0–1). opacity = 1: number, + + // Tint color multiplied with the overlay texture. color = 0xffffff: number | Color, + + // World-space transform defining the plane for planar + // projection. If null, cartographic (lat/lon) projection is + // used instead. frame = null: Matrix4, + + // Optional function `(url) => url` called before every fetch + // to allow URL rewriting or token injection. preprocessURL = null: function, + + // If true, the overlay alpha channel masks the underlying tile + // surface rather than blending on top of it. alphaMask = false: boolean, + + // If true, inverts the alpha channel before applying the mask + // or blend. alphaInvert = false: boolean, } ) @@ -166,22 +236,55 @@ feature's `properties` object. ```js constructor( { + // GeoJSON FeatureCollection or Feature object to render. If + // not provided, `url` must be set so the data can be fetched + // on init. geojson = null: Object, + + // URL to a GeoJSON file to fetch on initialization (used when + // `geojson` is not supplied directly). url = null: string, + + // Canvas resolution (pixels) used when compositing tiles. resolution = 256: number, + + // Per-feature style callback. When provided, overrides + // `strokeStyle`, `fillStyle`, `strokeWidth`, and + // `pointRadius`. getStyle?: ( feature: Object, properties: Object ) => VectorTileStyle | null, + + // Radius in pixels used to render Point features. pointRadius = 6: number, + + // Canvas stroke style for feature outlines. strokeStyle = 'white': string, + + // Stroke line width in pixels. strokeWidth = 2: number, + + // Canvas fill style for feature interiors. fillStyle = 'rgba( 255, 255, 255, 0.5 )': string, + + // Overlay opacity (0–1). opacity = 1: number, + + // Tint color. color = 0xffffff: number | Color, + + // Planar projection frame. If null, cartographic projection is + // used. frame = null: Matrix4, + + // URL rewriting callback. preprocessURL = null: function, + + // Use alpha channel as a surface mask. alphaMask = false: boolean, + + // Invert the alpha channel. alphaInvert = false: boolean, } ) @@ -206,10 +309,19 @@ npm install @mapbox/vector-tile pbf ```js constructor( { + // URL template with `{x}`, `{y}`, `{z}` placeholders. url?: string, + + // Number of zoom levels. levels = 20: number, + + // Projection scheme identifier. projection = 'EPSG:3857': string, + + // Canvas resolution for generated tile textures. resolution = 512: number, + + // Per-feature style callback. getStyle?: ( layerName: string, properties: Object | null @@ -238,8 +350,13 @@ npm install pmtiles @mapbox/vector-tile pbf ```js constructor( { + // URL to the `.pmtiles` archive. url?: string, + + // Canvas resolution for generated tile textures. resolution = 512: number, + + // Per-feature style callback. Only applies to vector archives. getStyle?: ( layerName: string, properties: Object | null @@ -271,6 +388,7 @@ and [OpenSeadragon](https://openseadragon.github.io). ```js constructor( { + // URL to the `.dzi` descriptor file. url?: string, } ) @@ -289,15 +407,38 @@ Google Maps Tile API. ```js constructor( { + // Google Maps API key. apiToken?: string, + + // Session creation options passed to the Google Maps Tile API + // when establishing a tile session. sessionOptions?: Object, + + // Automatically refresh the session token before it expires. autoRefreshToken = false: boolean, + + // URL to a Google logo image. If provided, it is included in + // the overlay attributions as required by Google's terms of + // service. logoUrl = null: string, + + // Overlay opacity (0–1). opacity = 1: number, + + // Tint color. color = 0xffffff: number | Color, + + // Planar projection frame. If null, cartographic projection is + // used. frame = null: Matrix4, + + // URL rewriting callback. preprocessURL = null: function, + + // Use alpha channel as a surface mask. alphaMask = false: boolean, + + // Invert the alpha channel. alphaInvert = false: boolean, } ) @@ -316,12 +457,27 @@ See the [TMS specification](https://wiki.osgeo.org/wiki/Tile_Map_Service_Specifi ```js constructor( { + // URL to the TMS `tilemapresource.xml` descriptor or tile + // template. url?: string, + + // Overlay opacity (0–1). opacity = 1: number, + + // Tint color. color = 0xffffff: number | Color, + + // Planar projection frame. If null, cartographic projection is + // used. frame = null: Matrix4, + + // URL rewriting callback. preprocessURL = null: function, + + // Use alpha channel as a surface mask. alphaMask = false: boolean, + + // Invert the alpha channel. alphaInvert = false: boolean, } ) @@ -340,21 +496,54 @@ See the [WMS specification](https://www.ogc.org/standard/wms/). ```js constructor( { + // WMS base URL. url?: string, + + // WMS layer name. layer?: string, + + // Coordinate reference system, e.g. `'EPSG:4326'`. crs?: string, + + // Image MIME type, e.g. `'image/png'`. format?: string, + + // Tile pixel size. tileDimension = 256: number, + + // WMS styles parameter. styles?: string, + + // WMS version string. version = '1.3.0': string, + + // Whether to request a transparent image. transparent = false: boolean, + + // Number of zoom levels. levels = 18: number, + + // Content bounding box in radians `[west, south, east, + // north]`. If null, uses full projection bounds. contentBoundingBox = null: Array | null, + + // Overlay opacity (0–1). opacity = 1: number, + + // Tint color. color = 0xffffff: number | Color, + + // Planar projection frame. If null, cartographic projection is + // used. frame = null: Matrix4, + + // URL rewriting callback. preprocessURL = null: function, + + // Use alpha channel as a surface mask. alphaMask = false: boolean, + + // Invert the alpha channel. alphaInvert = false: boolean, } ) @@ -374,17 +563,45 @@ directly. See the [WMTS specification](https://www.ogc.org/standard/wmts/). ```js constructor( { + // WMTS service URL. url?: string, + + // WMTS layer identifier. layer?: string, + + // TileMatrixSet identifier (e.g., 'GoogleMapsCompatible', + // 'EPSG:3857'). tileMatrixSet?: string, + + // Style identifier. style = 'default': string, + + // Output image format (e.g., 'image/png', 'image/jpeg'). format = 'image/jpeg': string, + + // WMTS dimension values dimensions = null: Object | null, + + // Custom TileMatrix identifiers per level tileMatrixLabels = null: Array | null, + + // Explicit per-level tile matrix definitions. When provided, + // `levels` and `tileMatrixLabels` are ignored. tileMatrices = null: Array | null, + + // Projection identifier ('EPSG:3857' or 'EPSG:4326'). Defaults + // to 'EPSG:3857' if not specified. projection = null: string | null, + + // Number of zoom levels. Ignored if `tileMatrices` is + // provided. levels = 20: number, + + // Default tile width and height in pixels. tileDimension = 256: number, + + // Content bounding box in radians, `[west, south, east, + // north]`. If null, uses full projection bounds. contentBoundingBox = null: Array | null, } ) @@ -403,15 +620,35 @@ geometry. See the [Slippy map tilenames specification](https://wiki.openstreetma ```js constructor( { + // URL template with `{x}`, `{y}`, `{z}` placeholders. url?: string, + + // Number of zoom levels. levels = 20: number, + + // Tile pixel size. tileDimension = 256: number, + + // Projection scheme identifier. projection = 'EPSG:3857': string, + + // Overlay opacity (0–1). opacity = 1: number, + + // Tint color. color = 0xffffff: number | Color, + + // Planar projection frame. If null, cartographic projection is + // used. frame = null: Matrix4, + + // URL rewriting callback. preprocessURL = null: function, + + // Use alpha channel as a surface mask. alphaMask = false: boolean, + + // Invert the alpha channel. alphaInvert = false: boolean, } ) @@ -430,14 +667,32 @@ as external asset types (Google 2D Maps, Bing Maps) that Ion proxies. ```js constructor( { + // Cesium Ion API token for authentication. apiToken?: string, + + // Cesium Ion asset ID. assetId?: number, + + // Automatically refresh the auth token before it expires. autoRefreshToken = false: boolean, + + // Overlay opacity (0–1). opacity = 1: number, + + // Tint color. color = 0xffffff: number | Color, + + // Planar projection frame. If null, cartographic projection is + // used. frame = null: Matrix4, + + // URL rewriting callback. preprocessURL = null: function, + + // Use alpha channel as a surface mask. alphaMask = false: boolean, + + // Invert the alpha channel. alphaInvert = false: boolean, } ) @@ -467,17 +722,41 @@ ramp. ```js constructor( { + // Show OBB bounding-box helpers. displayBoxBounds = false: boolean, + + // Show bounding-sphere helpers. displaySphereBounds = false: boolean, + + // Show bounding-region helpers. displayRegionBounds = false: boolean, + + // Also show ancestor bounding volumes for visible tiles. displayParentBounds = false: boolean, + + // Initial tile color mode. colorMode = ColorModes.NONE: number, + + // Color mode applied to bounding-volume helpers. boundsColorMode = ColorModes.NONE: number, + + // Maximum tree depth for depth-based coloring (`-1` = auto). maxDebugDepth = -1: number, + + // Maximum distance for distance-based coloring (`-1` = auto). maxDebugDistance = -1: number, + + // Maximum error for error-based coloring (`-1` = auto). maxDebugError = -1: number, + + // Callback `( tile, mesh )` used when `colorMode` is + // `CUSTOM_COLOR`. customColorCallback = null: function | null, + + // Replace tile materials with unlit `MeshBasicMaterial`. unlit = false: boolean, + + // Whether the plugin is active on init. enabled = true: boolean, } ) @@ -507,8 +786,15 @@ tile. Subclasses provide a concrete `imageSource` and override `getUrl` and ```js constructor( { + // Image source that provides tiling metadata and URL + // generation. imageSource = null: Object, + + // Shift tiles so the image is centered at the origin. center = false: boolean, + + // Apply recommended `TilesRenderer` settings (e.g. + // `errorTarget = 1`). useRecommendedSettings = true: boolean, } ) @@ -528,7 +814,11 @@ Extension of `ImageFormatPlugin` that projects tiled images onto ellipsoidal ```js constructor( { + // Projection shape: `'planar'` or `'ellipsoid'`. shape = 'planar': string, + + // Snap Mercator-projected poles to ±90° latitude to avoid + // seams. endCaps = true: boolean, } ) @@ -549,6 +839,8 @@ See the [TMS specification](https://wiki.osgeo.org/wiki/Tile_Map_Service_Specifi ```js constructor( { + // URL to the TMS `tilemapresource.xml` descriptor or tile + // template. url?: string, } ) @@ -566,15 +858,35 @@ Plugin that renders WMS (Web Map Service) image tiles projected onto 3D tile geo ```js constructor( { + // WMS base URL. url?: string, + + // WMS layer name. layer?: string, + + // Coordinate reference system, e.g. `'EPSG:4326'`. crs?: string, + + // Image MIME type, e.g. `'image/png'`. format?: string, + + // Tile pixel size. tileDimension = 256: number, + + // WMS styles parameter. styles?: string, + + // WMS version string. version = '1.3.0': string, + + // Whether to request a transparent image. transparent = false: boolean, + + // Number of zoom levels. levels = 18: number, + + // Content bounding box in radians `[west, south, east, + // north]`. If null, uses full projection bounds. contentBoundingBox = null: Array | null, } ) @@ -594,17 +906,45 @@ a URL template directly. ```js constructor( { + // WMTS service URL. url?: string, + + // WMTS layer identifier. layer?: string, + + // TileMatrixSet identifier (e.g., 'GoogleMapsCompatible', + // 'EPSG:3857'). tileMatrixSet?: string, + + // Style identifier. style = 'default': string, + + // Output image format (e.g., 'image/png', 'image/jpeg'). format = 'image/jpeg': string, + + // WMTS dimension values dimensions = null: Object | null, + + // Custom TileMatrix identifiers per level tileMatrixLabels = null: Array | null, + + // Explicit per-level tile matrix definitions. When provided, + // `levels` and `tileMatrixLabels` are ignored. tileMatrices = null: Array | null, + + // Projection identifier ('EPSG:3857' or 'EPSG:4326'). Defaults + // to 'EPSG:3857' if not specified. projection = null: string | null, + + // Number of zoom levels. Ignored if `tileMatrices` is + // provided. levels = 20: number, + + // Default tile width and height in pixels. tileDimension = 256: number, + + // Content bounding box in radians, `[west, south, east, + // north]`. If null, uses full projection bounds. contentBoundingBox = null: Array | null, } ) @@ -623,9 +963,16 @@ Plugin that renders XYZ/Slippy-map image tiles (e.g. OpenStreetMap) projected on ```js constructor( { + // URL template with `{x}`, `{y}`, `{z}` placeholders. url?: string, + + // Number of zoom levels. levels?: number, + + // Tile pixel size (defaults to 256). tileDimension?: number, + + // Projection scheme identifier. projection?: string, } ) @@ -643,8 +990,15 @@ Plugin that renders a Deep Zoom Image (DZI) as a 3D Tiles-compatible tiled textu ```js constructor( { + // URL to the `.dzi` descriptor file. url?: string, + + // Shift the DZI tiles so the image is centered at the origin + // rather than at the top-left corner. center = false: boolean, + + // If true, set the `TilesRenderer` error target to the device + // pixel ratio. useRecommendedSettings = true: boolean, } ) @@ -665,10 +1019,20 @@ both planar and ellipsoidal geometry via the `shape` option. ```js constructor( { + // Overlay instance to derive the tiling scheme from. overlay = null: ImageOverlay, + + // Geometry shape: `'planar'` or `'ellipsoid'`. Only + // meaningful for cartographic sources. shape = 'ellipsoid': string, + + // For Mercator ellipsoid mode, snap poles to ±90° lat. endCaps = true: boolean, + + // Shift planar tiles so the image is centered at origin. center = true: boolean, + + // Apply recommended TilesRenderer settings. useRecommendedSettings = true: boolean, } ) @@ -717,12 +1081,28 @@ support loading Draco-compressed point cloud files. ```js constructor( { + // Enable the `EXT_structural_metadata` and `EXT_mesh_features` + // extensions. metadata = true: boolean, + + // Enable the `CESIUM_RTC` extension. rtc = true: boolean, + + // Additional GLTF loader plugins to pass to + // `GLTFLoader.register`. plugins = []: Array, + + // A `DRACOLoader` instance for Draco-compressed geometry. dracoLoader = null: Object, + + // A `KTX2Loader` instance for KTX2-compressed textures. ktxLoader = null: Object, + + // A `MeshoptDecoder` for Meshopt-compressed meshes. meshoptDecoder = null: Object, + + // Automatically dispose the DRACO and KTX loaders on + // `dispose()`. autoDispose = true: boolean, } ) @@ -770,9 +1150,17 @@ Image sources are added via `addOverlay()` and removed via `deleteOverlay()`. ```js constructor( { + // The renderer used for constructing and rendering to render + // targets. renderer: WebGLRenderer, + + // Initial image overlay sources to add. overlays = []: Array, + + // Resolution of each generated tile texture in pixels. resolution = 256: number, + + // Allow tiles to be split to match image tile boundaries. enableTileSplitting = true: boolean, } ) @@ -891,10 +1279,20 @@ tile content from quantized-mesh buffers. ```js constructor( { + // Apply recommended error and fetch settings for terrain. useRecommendedSettings = true: boolean, + + // Override skirt length in metres; defaults to tile geometric + // error. skirtLength = null: number | null, + + // Blend skirt normals with tile surface for smoother edges. smoothSkirtNormals = true: boolean, + + // Compute vertex normals for the terrain mesh. generateNormals = true: boolean, + + // Generate a solid closed mesh (adds a bottom cap). solid = false: boolean, } ) @@ -914,13 +1312,31 @@ can be determined the tileset is oriented so the given `up` axis aligns to three ```js constructor( { + // Latitude in radians of the surface point to orient to + // (requires `lon`). lat = null: number | null, + + // Longitude in radians of the surface point to orient to + // (requires `lat`). lon = null: number | null, + + // Height in metres above the ellipsoid surface. height = 0: number, + + // Axis to orient toward three.js +Y when no lat/lon is + // available. Valid values are `±x`, `±y`, `±z`. up = '+z': string, + + // Whether to reposition the tileset to the origin. recenter = true: boolean, + + // Azimuth rotation in radians. azimuth = 0: number, + + // Elevation rotation in radians. elevation = 0: number, + + // Roll rotation in radians. roll = 0: number, } ) @@ -1064,14 +1480,31 @@ size when compression is enabled is fairly aggressive and may cause visual artif ```js constructor( { + // Generate vertex normals if absent. generateNormals = false: boolean, + + // Disable mipmap generation on tile textures. disableMipmaps = true: boolean, + + // Compress index buffers to the smallest fitting integer type. compressIndex = true: boolean, + + // Compress normal attributes. compressNormals = false: boolean, + + // Compress UV attributes. compressUvs = false: boolean, + + // Compress position attributes. compressPosition = false: boolean, + + // Target type for UV compression. uvType = Int8Array: TypedArrayConstructor, + + // Target type for normal compression. normalType = Int8Array: TypedArrayConstructor, + + // Target type for position compression. positionType = Int16Array: TypedArrayConstructor, } ) @@ -1100,6 +1533,9 @@ addShape( mesh: Object3D, direction: Vector3, { + // Maximum distance from the shape surface within which + // vertices are flattened. `Infinity` always flattens; `0` + // never flattens. threshold = Infinity: number, } ): void @@ -1150,8 +1586,14 @@ rendering. Works alongside `BatchedTilesPlugin` when present. ```js constructor( { + // Time in milliseconds for a tile to fully fade in or out. fadeDuration = 250: number, + + // Maximum simultaneous fade-out tiles. If exceeded, tiles pop + // instead of fading. maximumFadeOutTiles = 50: number, + + // Whether root-level tiles fade in on their first appearance. fadeRootTiles = false: boolean, } ) @@ -1181,7 +1623,13 @@ yet on the GPU. ```js constructor( { + // Milliseconds to wait after a tile is hidden before freeing + // its GPU data. Useful to avoid thrashing when the camera is + // moving. delay = 0: number, + + // Target GPU byte budget to unload down to. `0` means unload + // with no budget limit. bytesTarget = 0: number, } ) diff --git a/utils/docs/RenderDocsUtils.js b/utils/docs/RenderDocsUtils.js index 914a484a6..9c8b43b27 100644 --- a/utils/docs/RenderDocsUtils.js +++ b/utils/docs/RenderDocsUtils.js @@ -1,3 +1,32 @@ +// Wraps text to lines no longer than maxWidth characters, splitting on spaces. +function wordWrap( text, maxWidth ) { + + const lines = []; + let current = ''; + for ( const word of text.split( ' ' ) ) { + + if ( current.length === 0 ) { + + current = word; + + } else if ( current.length + 1 + word.length <= maxWidth ) { + + current += ' ' + word; + + } else { + + lines.push( current ); + current = word; + + } + + } + + if ( current.length > 0 ) lines.push( current ); + return lines; + +} + // Converts {@link url text} inline tags in a string to Markdown [text](url) links. export function resolveLinks( str ) { @@ -126,7 +155,7 @@ function renderParamLines( allParams, callbackMap ) { if ( nested ) { lines.push( '\t{' ); - for ( const opt of nested ) { + nested.forEach( ( opt, oi ) => { const name = opt.name.split( '.' ).pop(); const defStr = opt.defaultvalue !== undefined ? ` = ${ opt.defaultvalue }` : ''; @@ -134,6 +163,18 @@ function renderParamLines( allParams, callbackMap ) { const typeName = opt.type && opt.type.names && opt.type.names[ 0 ]; const callbackDoc = typeName && callbackMap[ typeName ]; + if ( opt.description ) { + + if ( oi > 0 ) lines.push( '' ); + const text = opt.description.split( '\n' ).join( ' ' ); + for ( const line of wordWrap( text, 60 ) ) { + + lines.push( `\t\t// ${ line }` ); + + } + + } + if ( callbackDoc ) { const cbParams = callbackDoc.params || []; @@ -158,7 +199,7 @@ function renderParamLines( allParams, callbackMap ) { } - } + } ); lines.push( `\t}${ comma }` );