| - Material extension framework to modify/inject/build custom shader code into existing materials at runtime from plugins. | - Material extension framework to modify/inject/build custom shader code into existing materials at runtime from plugins. | ||||
| - Extendable asset import, export and management pipeline with built-in support for gltf, glb, obj+mtl, fbx, materials(pmat/bmat), json, zip, png, jpeg, svg, webp, ktx2, ply, 3dm and many more. | - Extendable asset import, export and management pipeline with built-in support for gltf, glb, obj+mtl, fbx, materials(pmat/bmat), json, zip, png, jpeg, svg, webp, ktx2, ply, 3dm and many more. | ||||
| - Automatic serialization of all viewer and plugin settings in GLB(with custom extensions) and JSON formats. | - Automatic serialization of all viewer and plugin settings in GLB(with custom extensions) and JSON formats. | ||||
| - Built-in undo/redo support for user actions. | |||||
| - Automatic disposal of all three.js resources with built-in reference management. | - Automatic disposal of all three.js resources with built-in reference management. | ||||
| - Realtime Realistic Rendering with screen-space post-processing effects from [webgi](https://webgi.dev/). | - Realtime Realistic Rendering with screen-space post-processing effects from [webgi](https://webgi.dev/). | ||||
| - [GLTFMeshOptDecodePlugin](https://threepipe.org/plugin/GLTFMeshOptDecodePlugin.html) - Decode glTF files with [EXT_meshopt_compression](https://github.com/KhronosGroup/glTF/blob/main/extensions/2.0/Vendor/EXT_meshopt_compression/README.md) extension. | - [GLTFMeshOptDecodePlugin](https://threepipe.org/plugin/GLTFMeshOptDecodePlugin.html) - Decode glTF files with [EXT_meshopt_compression](https://github.com/KhronosGroup/glTF/blob/main/extensions/2.0/Vendor/EXT_meshopt_compression/README.md) extension. | ||||
| - [SimplifyModifierPlugin](https://threepipe.org/plugin/SimplifyModifierPlugin.html) - Boilerplate for plugin to simplify geometries | - [SimplifyModifierPlugin](https://threepipe.org/plugin/SimplifyModifierPlugin.html) - Boilerplate for plugin to simplify geometries | ||||
| - [MeshOptSimplifyModifierPlugin](https://threepipe.org/plugin/MeshOptSimplifyModifierPlugin.html) - Simplify geometries using [meshoptimizer](https://github.com/zeux/meshoptimizer) library | - [MeshOptSimplifyModifierPlugin](https://threepipe.org/plugin/MeshOptSimplifyModifierPlugin.html) - Simplify geometries using [meshoptimizer](https://github.com/zeux/meshoptimizer) library | ||||
| - [UndoManagerPlugin](https://threepipe.org/plugin/UndoManagerPlugin.html) - Adds support for undo/redo operations in the viewer. Used by other plugins to manage undo history. | |||||
| - [Packages](https://threepipe.org/guide/threepipe-packages.html) | - [Packages](https://threepipe.org/guide/threepipe-packages.html) | ||||
| - [@threepipe/webgi-plugins](https://webgi.dev) - Web [Global Illumination](https://en.wikipedia.org/wiki/Global_illumination) - Realistic rendering plugin pack (SSR, SSRTAO, HDR Bloom, TAA, Depth of Field, SSGI, etc.) | - [@threepipe/webgi-plugins](https://webgi.dev) - Web [Global Illumination](https://en.wikipedia.org/wiki/Global_illumination) - Realistic rendering plugin pack (SSR, SSRTAO, HDR Bloom, TAA, Depth of Field, SSGI, etc.) | ||||
| - [@threepipe/plugin-tweakpane](https://threepipe.org/package/plugin-tweakpane.html) [Tweakpane](https://tweakpane.github.io/docs/) UI Plugin | - [@threepipe/plugin-tweakpane](https://threepipe.org/package/plugin-tweakpane.html) [Tweakpane](https://tweakpane.github.io/docs/) UI Plugin |
| autoCenter: true, | autoCenter: true, | ||||
| autoScale: false, | autoScale: false, | ||||
| }) | }) | ||||
| console.log(result) | |||||
| // console.log(result) | |||||
| } | } | ||||
| _testStart() | _testStart() |
| * alphaTexture is added to the material | * alphaTexture is added to the material | ||||
| * This is separate from the alpha in base color texture. This is used when that is not supported in the viewer | * This is separate from the alpha in base color texture. This is used when that is not supported in the viewer | ||||
| * | * | ||||
| * Specification: https://webgi.xyz/docs/gltf-extensions/WEBGI_materials_alphamap.html | |||||
| * Specification: https://threepipe.org/docs/gltf-extensions/WEBGI_materials_alphamap.html | |||||
| */ | */ | ||||
| export class GLTFMaterialsAlphaMapExtension { | export class GLTFMaterialsAlphaMapExtension { | ||||
| static readonly WebGiMaterialsAlphaMapExtension = 'WEBGI_materials_alphamap' | static readonly WebGiMaterialsAlphaMapExtension = 'WEBGI_materials_alphamap' |
| * | * | ||||
| * bumpTexture and bumpScale are added to the material | * bumpTexture and bumpScale are added to the material | ||||
| * | * | ||||
| * Specification: https://webgi.xyz/docs/gltf-extensions/WEBGI_materials_bumpmap.html | |||||
| * Specification: https://threepipe.org/docs/gltf-extensions/WEBGI_materials_bumpmap.html | |||||
| */ | */ | ||||
| export class GLTFMaterialsBumpMapExtension { | export class GLTFMaterialsBumpMapExtension { | ||||
| static readonly WebGiMaterialsBumpMapExtension = 'WEBGI_materials_bumpmap' | static readonly WebGiMaterialsBumpMapExtension = 'WEBGI_materials_bumpmap' |
| * | * | ||||
| * displacementTexture and displacementScale are added to the material | * displacementTexture and displacementScale are added to the material | ||||
| * | * | ||||
| * Specification: https://webgi.xyz/docs/gltf-extensions/WEBGI_materials_displacementmap.html | |||||
| * Specification: https://threepipe.org/docs/gltf-extensions/WEBGI_materials_displacementmap.html | |||||
| */ | */ | ||||
| export class GLTFMaterialsDisplacementMapExtension { | export class GLTFMaterialsDisplacementMapExtension { | ||||
| static readonly WebGiMaterialsDisplacementMapExtension = 'WEBGI_materials_displacementmap' | static readonly WebGiMaterialsDisplacementMapExtension = 'WEBGI_materials_displacementmap' |
| * | * | ||||
| * lightMapTexture and lightMapIntensity are added to the material | * lightMapTexture and lightMapIntensity are added to the material | ||||
| * | * | ||||
| * Specification: https://webgi.xyz/docs/gltf-extensions/WEBGI_materials_lightmap.html | |||||
| * Specification: https://threepipe.org/docs/gltf-extensions/WEBGI_materials_lightmap.html | |||||
| */ | */ | ||||
| export class GLTFMaterialsLightMapExtension { | export class GLTFMaterialsLightMapExtension { | ||||
| static readonly WebGiMaterialsLightMapExtension = 'WEBGI_materials_lightmap' | static readonly WebGiMaterialsLightMapExtension = 'WEBGI_materials_lightmap' |
| if (o.assetType === 'widget') return false | if (o.assetType === 'widget') return false | ||||
| if (o.userData.userSelectable === false) return false | if (o.userData.userSelectable === false) return false | ||||
| if (o.userData.bboxVisible === false) return false | if (o.userData.bboxVisible === false) return false | ||||
| // todo colorwrite? | |||||
| o = o.parent | o = o.parent | ||||
| } | } | ||||
| return ret | return ret |
| import {AViewerPluginSync, ThreeViewer} from '../../viewer' | import {AViewerPluginSync, ThreeViewer} from '../../viewer' | ||||
| import {getUrlQueryParam, JSUndoManager, onChange} from 'ts-browser-helpers' | import {getUrlQueryParam, JSUndoManager, onChange} from 'ts-browser-helpers' | ||||
| /** | |||||
| * UndoManagerPlugin is a plugin for ThreeViewer that provides undo/redo functionality. | |||||
| * It uses the JSUndoManager(from ts-browser-helpers) library to maintain a common undo/redo history across the viewer and other plugins. | |||||
| */ | |||||
| // @uiPanelContainer('Undo Manager') | // @uiPanelContainer('Undo Manager') | ||||
| export class UndoManagerPlugin extends AViewerPluginSync { | export class UndoManagerPlugin extends AViewerPluginSync { | ||||
| public static readonly PluginType = 'UndoManagerPlugin' | public static readonly PluginType = 'UndoManagerPlugin' |
| /** | /** | ||||
| * ClearcoatTint Materials Extension | * ClearcoatTint Materials Extension | ||||
| * | * | ||||
| * Specification: https://webgi.xyz/docs/gltf-extensions/WEBGI_materials_clearcoat_tint.html (todo - fix link) | |||||
| * Specification: https://threepipe.org/docs/gltf-extensions/WEBGI_materials_clearcoat_tint.html (todo - fix link) | |||||
| */ | */ | ||||
| class GLTFMaterialsClearcoatTintExtensionImport implements GLTFLoaderPlugin { | class GLTFMaterialsClearcoatTintExtensionImport implements GLTFLoaderPlugin { | ||||
| public name: string | public name: string | ||||
| import: (p) => new GLTFMaterialsClearcoatTintExtensionImport(p), | import: (p) => new GLTFMaterialsClearcoatTintExtensionImport(p), | ||||
| export: glTFMaterialsClearcoatTintExtensionExport, | export: glTFMaterialsClearcoatTintExtensionExport, | ||||
| textures: undefined, | textures: undefined, | ||||
| } satisfies AssetManager['gltfExtensions'][number] | |||||
| } satisfies AssetManager['gltfExtensions'][number] |
| /** | /** | ||||
| * FragmentClipping Materials Extension | * FragmentClipping Materials Extension | ||||
| * | * | ||||
| * Specification: https://webgi.xyz/docs/gltf-extensions/WEBGI_materials_fragment_clipping_extension.html | |||||
| * Specification: https://threepipe.org/docs/gltf-extensions/WEBGI_materials_fragment_clipping_extension.html | |||||
| */ | */ | ||||
| class GLTFMaterialsCustomBumpMapImport implements GLTFLoaderPlugin { | class GLTFMaterialsCustomBumpMapImport implements GLTFLoaderPlugin { | ||||
| public name: string | public name: string |
| /** | /** | ||||
| * FragmentClipping Materials Extension | * FragmentClipping Materials Extension | ||||
| * | * | ||||
| * Specification: https://webgi.xyz/docs/gltf-extensions/WEBGI_materials_fragment_clipping_extension.html | |||||
| * Specification: https://threepipe.org/docs/gltf-extensions/WEBGI_materials_fragment_clipping_extension.html | |||||
| */ | */ | ||||
| class GLTFMaterialsFragmentClippingExtensionImport implements GLTFLoaderPlugin { | class GLTFMaterialsFragmentClippingExtensionImport implements GLTFLoaderPlugin { | ||||
| public name: string | public name: string | ||||
| import: (p) => new GLTFMaterialsFragmentClippingExtensionImport(p), | import: (p) => new GLTFMaterialsFragmentClippingExtensionImport(p), | ||||
| export: glTFMaterialsFragmentClippingExtensionExport, | export: glTFMaterialsFragmentClippingExtensionExport, | ||||
| textures: undefined, | textures: undefined, | ||||
| } satisfies AssetManager['gltfExtensions'][number] | |||||
| } satisfies AssetManager['gltfExtensions'][number] |
| /** | /** | ||||
| * FragmentClipping Materials Extension | * FragmentClipping Materials Extension | ||||
| * | * | ||||
| * Specification: https://webgi.xyz/docs/gltf-extensions/WEBGI_materials_fragment_clipping_extension.html (todo - fix link) | |||||
| * Specification: https://threepipe.org/docs/gltf-extensions/WEBGI_materials_fragment_clipping_extension.html (todo - fix link) | |||||
| */ | */ | ||||
| class GLTFMaterialsNoiseBumpMaterialImport implements GLTFLoaderPlugin { | class GLTFMaterialsNoiseBumpMaterialImport implements GLTFLoaderPlugin { | ||||
| public name: string | public name: string |
| {text: 'glTF Mesh Lines', link: 'notes/gltf-mesh-lines'}, | {text: 'glTF Mesh Lines', link: 'notes/gltf-mesh-lines'}, | ||||
| {text: 'Setting Background', link: 'notes/scene-background'}, | {text: 'Setting Background', link: 'notes/scene-background'}, | ||||
| {text: 'ShaderToy Shader Tutorial', link: 'notes/shadertoy-player'}, | {text: 'ShaderToy Shader Tutorial', link: 'notes/shadertoy-player'}, | ||||
| {text: 'Using Vanilla Three.js code', link: 'notes/vanilla-threejs'}, | |||||
| {text: 'Three.js properties in glTF', link: 'notes/gltf-three-extras-ext'}, | |||||
| ] | ] | ||||
| }, | }, | ||||
| { | { |
| Plugins to add/configure interaction and user editable elements to the viewer. | Plugins to add/configure interaction and user editable elements to the viewer. | ||||
| - [DropzonePlugin](../plugin/DropzonePlugin) - Drag and drop local files to import and automatically load. Also provides hooks for custom processing. | - [DropzonePlugin](../plugin/DropzonePlugin) - Drag and drop local files to import and automatically load. Also provides hooks for custom processing. | ||||
| - [UndoManagerPlugin](../plugin/UndoManagerPlugin) - Adds support for undo/redo operations in the viewer. It can be used to manage the history of changes made to the scene, objects, materials, etc. | |||||
| - [PickingPlugin](../plugin/PickingPlugin) - Adds support for selecting objects in the viewer with user interactions(click and hover) and shows selection widgets. | - [PickingPlugin](../plugin/PickingPlugin) - Adds support for selecting objects in the viewer with user interactions(click and hover) and shows selection widgets. | ||||
| - [LoadingScreenPlugin](../plugin/LoadingScreenPlugin) - Shows a configurable loading screen overlay over the canvas which can be extended to show a loader during any kind of processing. | - [LoadingScreenPlugin](../plugin/LoadingScreenPlugin) - Shows a configurable loading screen overlay over the canvas which can be extended to show a loader during any kind of processing. | ||||
| - [FullScreenPlugin](../plugin/FullScreenPlugin) - Provides helpers for entering the fullscreen mode in browsers. | - [FullScreenPlugin](../plugin/FullScreenPlugin) - Provides helpers for entering the fullscreen mode in browsers. |
| <script type="module"> | <script type="module"> | ||||
| const {ThreeViewer, DepthBufferPlugin} = threepipe | const {ThreeViewer, DepthBufferPlugin} = threepipe | ||||
| // import {ThreeViewer, DepthBufferPlugin} from 'threepipe' // using npm or importmaps | // import {ThreeViewer, DepthBufferPlugin} from 'threepipe' // using npm or importmaps | ||||
| window.THREE = threepipe // optional (if using THREE.Xyz style code) | |||||
| const viewer = new ThreeViewer({canvas: document.getElementById('three-canvas')}) | const viewer = new ThreeViewer({canvas: document.getElementById('three-canvas')}) | ||||
| Check out the details about [ThreeViewer API](../guide/viewer-api) and more [plugins](../guide/core-plugins.md). | Check out the details about [ThreeViewer API](../guide/viewer-api) and more [plugins](../guide/core-plugins.md). | ||||
| ::: details Import Maps | |||||
| Import maps are an upcoming feature in browsers that allows you to import modules using a simple JSON format. This is useful for loading modules without needing a bundler or package manager. | |||||
| Threepipe can be used with import maps to load modules directly from a CDN like unpkg or jsdelivr. | |||||
| ```html | |||||
| <script async src="https://unpkg.com/es-module-shims@1.6.3/dist/es-module-shims.js"></script> | |||||
| <script type="importmap">{ | |||||
| "imports": { | |||||
| "threepipe": "https://unpkg.com/threepipe/dist/index.mjs", | |||||
| "@threepipe/plugin-tweakpane": "https://unpkg.com/@threepipe/plugin-tweakpane/dist/index.mjs" | |||||
| "three": "https://unpkg.com/threepipe/dist/index.mjs", | |||||
| } | |||||
| }</script> | |||||
| <script type="module"> | |||||
| import {ThreeViewer} from 'threepipe' | |||||
| // your code | |||||
| </script> | |||||
| ``` | |||||
| In the above code, we are adding `es-module-shims` script to support import maps in browsers that do not support it natively. Then, we define an import map with the `threepipe` module pointing to the latest version on `unpkg`. Finally, we can import `ThreeViewer` from `threepipe` and use it in our code. | |||||
| A reference to "three" is also added to be same as threepipe, this way any libraries/addons that import from three will now import from threepipe instead. | |||||
| ::: | |||||
| ### NPM | ### NPM | ||||
| #### Installation | #### Installation |
| - Modular rendering pipeline with built-in deferred rendering, post-processing, RGBM HDR rendering, etc. | - Modular rendering pipeline with built-in deferred rendering, post-processing, RGBM HDR rendering, etc. | ||||
| - Material extension framework to modify/inject/build custom shader code into existing materials at runtime from plugins. | - Material extension framework to modify/inject/build custom shader code into existing materials at runtime from plugins. | ||||
| - Extendable asset import, export and management pipeline with built-in support for gltf, glb, obj+mtl, fbx, materials(pmat/bmat), json, zip, png, jpeg, svg, webp, ktx2, ply, 3dm and many more. | - Extendable asset import, export and management pipeline with built-in support for gltf, glb, obj+mtl, fbx, materials(pmat/bmat), json, zip, png, jpeg, svg, webp, ktx2, ply, 3dm and many more. | ||||
| - Built-in undo/redo support for user actions. | |||||
| - Automatic serialization of all viewer and plugin settings in GLB(with custom extensions) and JSON formats. | - Automatic serialization of all viewer and plugin settings in GLB(with custom extensions) and JSON formats. | ||||
| - Automatic disposal of all three.js resources with built-in reference management. | - Automatic disposal of all three.js resources with built-in reference management. | ||||
| # Serialization | # Serialization | ||||
| Easy serialization of all threepipe and most three.js objects are supported out of the box using the Asset Manager. Fine control over serialization is also supported using the [ThreeSerialization](https://threepipe.org/docs/classes/ThreeSerialization.html) class | |||||
| Easy serialization of all threepipe and most three.js objects are supported out of the box using the Asset Manager. | |||||
| Complete scene, and 3D objects, can be serialized in glTF format, which saves the 3D data is a standardized format supported by the industry. Custom data like three.js properties, plugin configurations, and viewer configurations are also automatically serialized in glTF format using custom extensions. Read the [glTF Extras Extensions note](./../notes/gltf-three-extras-ext) for more details. | |||||
| Fine control over serialization is also supported using the [ThreeSerialization](https://threepipe.org/docs/classes/ThreeSerialization.html) class | |||||
| Call `ThreeSerialization.serialize` on any object to serialize it. | Call `ThreeSerialization.serialize` on any object to serialize it. | ||||
| and `ThreeSerialization.deserialize` to deserialize the serialized object. | and `ThreeSerialization.deserialize` to deserialize the serialized object. |
| #next: | #next: | ||||
| # text: '@threepipe Packages' | # text: '@threepipe Packages' | ||||
| # link: './threepipe-packages' | # link: './threepipe-packages' | ||||
| next: false | |||||
| aside: false | |||||
| --- | --- | ||||
| # @threepipe Packages | # @threepipe Packages |
| next: | next: | ||||
| text: 'Serialization' | text: 'Serialization' | ||||
| link: './serialization' | link: './serialization' | ||||
| aside: false | |||||
| --- | --- | ||||
| # UI Configuration | # UI Configuration | ||||
| The `uiConfig` is also added to all three.js objects and materials when they are added to the scene. | The `uiConfig` is also added to all three.js objects and materials when they are added to the scene. | ||||
| The UIs can be generated at runtime using any of the UI plugins like [TweakpaneUIPlugin](../package/plugin-tweakpane), [BlueprintJsUiPlugin](../package/plugin-blueprintjs) | |||||
| The UIs can be generated at runtime using any of the UI plugins like [TweakpaneUIPlugin](../package/plugin-tweakpane), [BlueprintJsUiPlugin](../package/plugin-blueprintjs). They have full undo/redo support and interface with `UndoMangerPlugin` to maintain a common history with the rest of the viewer. | |||||
| An example showing how to create a UI for a material | An example showing how to create a UI for a material | ||||
| <iframe src="https://threepipe.org/examples/material-uiconfig/" style="width:100%;height:600px;border:none;"></iframe> | |||||
| ```typescript | ```typescript | ||||
| const ui = viewer.addPluginSync(TweakpaneUiPlugin) | const ui = viewer.addPluginSync(TweakpaneUiPlugin) | ||||
| ui.appendChild(material.uiConfig) | ui.appendChild(material.uiConfig) | ||||
| ``` | ``` | ||||
| See it in action: https://threepipe.org/examples/#material-uiconfig/ | |||||
| Check more examples showing [Viewer UI](https://threepipe.org/examples/#viewer-uiconfig/), [Scene UI](https://threepipe.org/examples/#scene-uiconfig/), [Object UI](https://threepipe.org/examples/#object-uiconfig/), [Camera UI](https://threepipe.org/examples/#camera-uiconfig/) | |||||
| Check more examples showing [Viewer UI](https://threepipe.org/examples/#viewer-uiconfig/), [Scene UI](https://threepipe.org/examples/#scene-uiconfig/), [Object UI](https://threepipe.org/examples/#object-uiconfig/), [Camera UI](https://threepipe.org/examples/#camera-uiconfig/), [Material UI](https://threepipe.org/examples/#material-uiconfig/) | |||||
| ::: info | ::: info | ||||
| [TweakpaneEditorPlugin](../package/plugin-tweakpane-editor) further uses the Tweakpane configuration panel along with various plugins to create a 3d editor. | [TweakpaneEditorPlugin](../package/plugin-tweakpane-editor) further uses the Tweakpane configuration panel along with various plugins to create a 3d editor. |
| --- | |||||
| prev: | |||||
| text: 'Using Vanilla Three.js style code' | |||||
| link: './vanilla-threejs' | |||||
| next: false | |||||
| aside: false | |||||
| --- | |||||
| # Saving three.js properties in glTF | |||||
| Threepipe support saving three.js object, material and light properties in glTF files automatically. | |||||
| This is done using custom glTF extensions that are added to the glTF file when exporting. | |||||
| If the files exported from threepipe exporter plugin or any of the editors is opened in external three.js editor, it cannot read these extra properties without the extensions support. | |||||
| ## Extensions | |||||
| - `WEBGI_object3d_extras` | |||||
| - Implemented in [GLTFObject3DExtrasExtension](https://threepipe.org/docs/classes/GLTFObject3DExtrasExtension.html) | |||||
| - This extension saves additional properties of `Object3D` like `visible`, `castShadow`, `frustumCulled`, etc. | |||||
| - Reference from three.js -> `ObjectLoader` | |||||
| - `WEBGI_material_extras` | |||||
| - Implemented in [GLTFMaterialExtrasExtension](https://threepipe.org/docs/classes/GLTFMaterialExtrasExtension.html) | |||||
| - This extension saves additional properties of `Material` like `emissiveIntensity`, `flatShading`, `blending`, etc. | |||||
| - Reference from three.js -> `MaterialLoader` | |||||
| - `WEBGI_light_extras` | |||||
| - Implemented in [GLTFLightExtrasExtension](https://threepipe.org/docs/classes/GLTFLightExtrasExtension.html) | |||||
| - This extension saves additional properties of `Light` like `shadow`. | |||||
| - This is used alongside `WEBGI_object3d_extras` extension for Light objects | |||||
| - `WEBGI_materials_alphamap` | |||||
| - Implemented in [GLTFMaterialsAlphaMapExtension](https://threepipe.org/docs/classes/GLTFMaterialsAlphaMapExtension.html) | |||||
| - This extension saves the alpha map texture for materials that have an `alphaMap` property. | |||||
| - `WEBGI_materials_bumpmap` | |||||
| - Implemented in [GLTFMaterialsBumpMapExtension](https://threepipe.org/docs/classes/GLTFMaterialsBumpMapExtension.html) | |||||
| - This extension saves the bump map texture for materials that have an `bumpMap` property. | |||||
| - `WEBGI_materials_displacementmap` | |||||
| - Implemented in [GLTFMaterialsDisplacementMapExtension](https://threepipe.org/docs/classes/GLTFMaterialsDisplacementMapExtension.html) | |||||
| - This extension saves the displacement map texture for materials that have an `displacementMap` property. | |||||
| - `WEBGI_materials_lightmap` | |||||
| - Implemented in [GLTFMaterialsLightMapExtension](https://threepipe.org/docs/classes/GLTFMaterialsLightMapExtension.html) | |||||
| - This extension saves the light map texture for materials that have an `lightMap` property. | |||||
| - `WEBGI_viewer` | |||||
| - Implemented in [GLTFViewerConfigExtension](https://threepipe.org/docs/classes/GLTFViewerConfigExtension.html) | |||||
| - Saves all the `ThreeViewer`, `RootScene`, `RenderManager` and all plugin configurations in the glTF file as JSON object. Textures are saved as binary blob or base64 encoded string depending on the file format. | |||||
| Threepipe includes some more extensions that are defined within plugins like `customBumpMapGLTFExtension`, `clearCoatTintGLTFExtension` etc. | |||||
| These custom extensions are written as standard three.js GLTFLoader and GLTFExporter extensions, so they can _ideally_ be used with any three.js project. | |||||
| ## glTF Transform Extensions | |||||
| It's possible to use the custom extensions with the [gltf-transform](https://gltf-transform.donmccurdy.com/) library as well. | |||||
| To do that, a custom extension implementation/class has to be created. Fortunately, in threepipe this can be done automatically at runtime. | |||||
| `@threepipe/plugin-gltf-transform` package provides `createGenericExtensionClass` function, and can be used to create an extension class that can be used with glTF Transform library. | |||||
| ```typescript | |||||
| const MyExtension = createGenericExtensionClass(GLTFMaterialsLightMapExtension.WebGiMaterialsLightMapExtension, GLTFMaterialsLightMapExtension.Textures) | |||||
| const io = new WebIO().registerExtensions([MyExtension]) | |||||
| ``` | |||||
| It is also possible to get all the extensions supported for `gltf-transform` using the `GLTFDracoExportPlugin` - | |||||
| ```typescript | |||||
| const plugin = viewer.getPlugin(GLTFDracoExportPlugin) // add the plugin before if not added | |||||
| const ALL_THREEPIPE_EXTENSIONS = plugin.gltfTransformExtensions | |||||
| const io = new WebIO().registerExtensions(ALL_THREEPIPE_EXTENSIONS) | |||||
| ``` | |||||
| Checkout the [Serialization guide](./../guide/serialization) for more details on how to serialize and deserialize js in threepipe. |
| text: 'Setting Background Color and Images' | text: 'Setting Background Color and Images' | ||||
| link: './scene-background' | link: './scene-background' | ||||
| next: false | |||||
| next: | |||||
| text: 'Using Vanilla Three.js style code' | |||||
| link: './vanilla-threejs' | |||||
| aside: false | aside: false | ||||
| --- | --- | ||||
| --- | |||||
| prev: | |||||
| text: 'ShaderToy Shaders in Three.js' | |||||
| link: './shadertoy-player' | |||||
| next: | |||||
| text: 'Saving three.js properties in glTF' | |||||
| link: './gltf-three-extras-ext' | |||||
| aside: false | |||||
| --- | |||||
| # Using Vanilla Three.js code in Threepipe | |||||
| Threepipe is built on top of three.js, so most vanilla three.js code should work without any issues. | |||||
| However, since threepipe uses [a fork of three.js](https://github.com/repalash/three.js-modded), it is bundled within the package instead of being a separate dependency. | |||||
| This means you can use threepipe as a drop-in replacement for three.js in many cases. | |||||
| The three.js fork is [updated till r158](https://github.com/repalash/three.js-modded/releases), and is regularly updated with new features and bug fixes. | |||||
| ## Importing three.js objects | |||||
| Classes, types, constants, and functions from three.js can be imported from `threepipe` in the same way as you would import from `three`. | |||||
| With npm modules - | |||||
| ```typescript | |||||
| import { Scene, PerspectiveCamera, WebGLRenderer, Mesh, BoxGeometry, MeshBasicMaterial } from 'threepipe'; | |||||
| ``` | |||||
| In many cases, threepipe provides an extended class as an alternative to the original three.js class. | |||||
| These extended classes provide additional features and methods that are not available in the original three.js classes and provide better experience with typescript and autocomplete. It's not necessary to use these extended classes, and standard ones would work fine, but they are recommended for better experience. | |||||
| Some examples are - | |||||
| - `MeshPhysicalMaterial`, `MeshStandardMaterial` -> `PhysicalMaterial` | |||||
| - `MeshBasicMaterial` -> `UnlitMaterial` | |||||
| - `Mesh2` -> `Mesh` | |||||
| - `BufferGeometry2` -> `BufferGeometry` | |||||
| Check more [here](./../guide/viewer-api#other-classes-and-interfaces) | |||||
| Read the [Viewer API guide](./../guide/viewer-api) for more details on classes provided by threepipe. | |||||
| ## Using `THREE.` style | |||||
| You can use the `THREE.` style code in Threepipe, but you need to import the necessary classes from `threepipe` instead of `three`. | |||||
| With npm modules - | |||||
| ```typescript | |||||
| import * as THREE from 'threepipe'; | |||||
| ``` | |||||
| With UMD modules - | |||||
| ```html | |||||
| <script>window.THREE = window.threepipe</script> | |||||
| ``` | |||||
| With import map - | |||||
| ```html | |||||
| <script async src="https://unpkg.com/es-module-shims@1.6.3/dist/es-module-shims.js"></script> | |||||
| <script type="importmap"> | |||||
| { | |||||
| "imports": { | |||||
| "three": "https://unpkg.com/threepipe/dist/index.mjs", | |||||
| "threepipe": "https://unpkg.com/threepipe/dist/index.mjs" | |||||
| } | |||||
| } | |||||
| </script> | |||||
| ``` | |||||
| ## Using packages that depend on `three` | |||||
| If you are using packages that depend on `three`, override in package.json to use `threepipe` as the `three` dependency. | |||||
| ```json | |||||
| { | |||||
| "dependencies": { | |||||
| "three": "./node_modules/threepipe/", | |||||
| "threepipe": "^0.0.51" | |||||
| }, | |||||
| "overrides": { | |||||
| "three": "$three" | |||||
| } | |||||
| } | |||||
| ``` | |||||
| If using `vite`, add a plugin to replace `three` import to `threepipe` in your `vite.config.js`(or rollup) | |||||
| ```javascript | |||||
| import {defineConfig} from 'vite' | |||||
| import replace from '@rollup/plugin-replace'; | |||||
| export default defineConfig({ | |||||
| plugins: [ | |||||
| replace({ | |||||
| 'from \'three\'': 'from \'threepipe\'', | |||||
| 'from \'three/examples/jsm/loaders/GLTFLoader.js\'': 'from \'threepipe\'', | |||||
| 'from \'three/examples/jsm/postprocessing/Pass.js\'': 'from \'threepipe\'', | |||||
| 'from \'three/examples/jsm/utils/BufferGeometryUtils.js\'': 'from \'threepipe\'', | |||||
| // add more that are being used | |||||
| // 'from \'three/examples/jsm/.*\'': 'from \'threepipe\'', // Note - regex doesnt work... | |||||
| delimiters: ['', ''], | |||||
| preventAssignment: true, | |||||
| }), | |||||
| replace({ // this is added to throw an error, in that case, add it to above | |||||
| 'from \'three/': 'from \'unknown/', | |||||
| delimiters: ['', ''], | |||||
| preventAssignment: true, | |||||
| }), | |||||
| ] | |||||
| }) | |||||
| ``` | |||||
| [//]: # (todo add sample with vite for above using some three.js library that has it as dependency/peerDependency) |
| --- | --- | ||||
| prev: | prev: | ||||
| text: 'SimplifyModifierPlugin' | |||||
| link: './SimplifyModifierPlugin' | |||||
| text: 'SimplifyModifierPlugin' | |||||
| link: './SimplifyModifierPlugin' | |||||
| next: false | |||||
| next: | |||||
| text: 'UndoManagerPlugin' | |||||
| link: './UndoManagerPlugin' | |||||
| --- | --- | ||||
| # MeshOptSimplifyModifierPlugin | # MeshOptSimplifyModifierPlugin |
| --- | |||||
| prev: | |||||
| text: 'MeshOptSimplifyModifierPlugin' | |||||
| link: './MeshOptSimplifyModifierPlugin' | |||||
| next: false | |||||
| --- | |||||
| # UndoManagerPlugin | |||||
| [//]: # (todo: image) | |||||
| [Example](https://threepipe.org/examples/#transform-controls-plugin/) — | |||||
| [Source Code](https://github.com/repalash/threepipe/blob/master/src/plugins/rendering/UndoManagerPlugin.ts) — | |||||
| [API Reference](https://threepipe.org/docs/classes/UndoManagerPlugin.html) | |||||
| UndoManagerPlugin adds support for undo/redo operations in the viewer. | |||||
| It can be used to manage the history of changes made to the scene, objects, materials, etc. | |||||
| It uses the [`JSUndoManager`](https://github.com/repalash/ts-browser-helpers/blob/master/src/JSUndoManager.ts)(from [ts-browser-helpers](https://repalash.com/ts-browser-helpers)) to maintain a common undo/redo history across the viewer and other plugins. | |||||
| The plugin is used automatically by `TweakpaneUiPlugin`, `BlueprintJsUiPlugin`, `PickingPlugin`, `TransformControlsPlugin`, and other plugins that support undo/redo operations. | |||||
| It is not _required_ to be added to the viewer explicitly when using any of the UI plugins, but can be added if you want to use it directly. | |||||
| ```typescript | |||||
| viewer.addPlugin(UndoManagerPlugin) | |||||
| let undoManager: JSUndoManager | undefined | |||||
| // listen for plugin to be added/removed/changed | |||||
| viewer.forPlugin<UndoManagerPlugin>('UndoManagerPlugin', (um)=> { | |||||
| undoManager = um.undoManager | |||||
| }, ()=> undoManager = undefined) | |||||
| // on button click | |||||
| undoManager.record({ | |||||
| // my command | |||||
| }) | |||||
| ``` |