99 lines
4.5 KiB
Markdown
99 lines
4.5 KiB
Markdown
# `<model-viewer-effects>`
|
|
|
|
|
|
|
|
|
|
`<model-viewer-effects>` is a web component library addon for `<model-viewer>` that makes adding post-processing
|
|
effects to your models easy to do, on as many browsers and devices as possible.
|
|
|
|
`<model-viewer-effects>` strives to give you great defaults for rendering quality and
|
|
performance.
|
|
|
|
|
|
|
|
[Examples](https://modelviewer.dev/examples/postprocessing/) • [Documentation](https://modelviewer.dev/docs/mve)
|
|
## Usage
|
|
Using effects is as simple as adding the `<effect-composer>` inside your `<model-viewer>`, and placing any effects inside the composer component.
|
|
|
|
```html
|
|
<model-viewer src="...">
|
|
<effect-composer>
|
|
<bloom-effect></bloom-effect>
|
|
</effect-composer>
|
|
</model-viewer>
|
|
```
|
|
|
|
### PostProcessing
|
|
`<model-viewer-effects>` uses the [postprocessing](https://github.com/pmndrs/postprocessing) library under the hood, for its superior [performance](https://github.com/pmndrs/postprocessing#performance) and support.
|
|
|
|
In addition to the built-in effects wrapped by this library, you can add any custom effects/passes that follow the [postprocessing spec](https://github.com/pmndrs/postprocessing/wiki/Custom-Passes).
|
|
|
|
### *XR Support*
|
|
The effects are not supported in the `<model-viewer>` XR modes, which will render as usual.
|
|
|
|
## Installing
|
|
### NPM
|
|
|
|
The `<model-viewer-effects>` library can be installed from [NPM](https://npmjs.org):
|
|
|
|
```sh
|
|
npm install three @google/model-viewer @google/model-viewer-effects
|
|
```
|
|
|
|
### HTML
|
|
|
|
`<model-viewer-effects>` and `<model-viewer>` share a [Three.js](https://threejs.org/) dependency. In order to avoid version conflicts, you should bring Three through an `import-map`:
|
|
|
|
```html
|
|
<!-- ES-Shims for older browser compatibility -->
|
|
<script async src="https://ga.jspm.io/npm:es-module-shims@1.7.1/dist/es-module-shims.js"></script>
|
|
|
|
<!-- Import Three.js using an import-map -->
|
|
<script type="importmap">
|
|
{
|
|
"imports": {
|
|
"three": "https://cdn.jsdelivr.net/npm/three@^0.172.0/build/three.module.min.js"
|
|
}
|
|
}
|
|
</script>
|
|
```
|
|
|
|
You should then bring the `module` version of `<model-viewer>`, along with `<model-viewer-effects>` from your favourite CDN, such as [jsDelivr](https://www.jsdelivr.com/package/npm/@google/model-viewer):
|
|
|
|
|
|
```html
|
|
<script type="module" src=" https://cdn.jsdelivr.net/npm/@google/model-viewer/dist/model-viewer-module.min.js "></script>
|
|
|
|
<script type="module" src=" https://cdn.jsdelivr.net/npm/@google/model-viewer-effects/dist/model-viewer-effects.min.js "></script>
|
|
```
|
|
|
|
## Browser Support
|
|
|
|
`<model-viewer-effects>` is supported on the last 2 major versions of all evergreen
|
|
desktop and mobile browsers, and on all platforms (Android, IOS, MacOS, Windows, Linux).
|
|
|
|
| | <img src="https://github.com/alrra/browser-logos/raw/master/src/chrome/chrome_32x32.png" width="16"> Chrome | <img src="https://github.com/alrra/browser-logos/raw/master/src/firefox/firefox_32x32.png" width="16"> Firefox | <img src="https://github.com/alrra/browser-logos/raw/master/src/safari/safari_32x32.png" width="16"> Safari | <img src="https://github.com/alrra/browser-logos/raw/master/src/edge/edge_32x32.png" width="16"> Edge |
|
|
| -------- | --- | --- | --- | --- |
|
|
| Desktop | ✅ | ✅ | ✅ | ✅ |
|
|
| Mobile | ✅ | ✅ | ✅ | ✅ |
|
|
|
|
`<model-viewer-effects>` builds upon standard web platform APIs so that the performance,
|
|
capabilities and compatibility of the library get better as the web evolves.
|
|
|
|
## Development
|
|
|
|
To get started, follow the instructions in [the main README.md file](../../README.md).
|
|
|
|
The following commands are available when developing `<model-viewer-effects>`:
|
|
|
|
Command | Description
|
|
------------------------------- | -----------
|
|
`npm run build` | Builds all `<model-viewer-effects>` distributable files
|
|
`npm run build:dev` | Builds a subset of distributable files (faster than `npm run build`)
|
|
`npm run test` | Run `<model-viewer-effects>` unit tests
|
|
`npm run clean` | Deletes all build artifacts
|
|
`npm run dev` | Starts `tsc` and `rollup` in "watch" mode, causing artifacts to automatically rebuild upon incremental changes
|
|
|
|
|
|
----
|
|
*Rocket Ship by Daniel Melchior [CC-BY](https://creativecommons.org/licenses/by/3.0/) via [Poly Pizza](https://poly.pizza/m/9dyJn4gp7U8)* |