From b176dc4fb782b151ba2f2acb9b3b1434db897ba2 Mon Sep 17 00:00:00 2001 From: Peter Date: Thu, 31 Aug 2023 16:03:32 +0200 Subject: [PATCH] feat(SVG): add docs --- docs/.vitepress/config.ts | 1 + docs/guide/loaders/svg.md | 88 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 89 insertions(+) create mode 100644 docs/guide/loaders/svg.md diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index bc96415d..960eb086 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -60,6 +60,7 @@ export default defineConfig({ { text: 'useFBX', link: '/guide/loaders/use-fbx' }, { text: 'FBXModel', link: '/guide/loaders/fbx-model' }, { text: 'useVideoTexture', link: '/guide/loaders/use-video-texture' }, + { text: 'SVG', link: '/guide/loaders/svg' }, ], }, { diff --git a/docs/guide/loaders/svg.md b/docs/guide/loaders/svg.md new file mode 100644 index 00000000..850d0faa --- /dev/null +++ b/docs/guide/loaders/svg.md @@ -0,0 +1,88 @@ +# SVG + +A wrapper around the `three` [SVGLoader](https://threejs.org/examples/?q=sv#webgl_loader_svg), this component allows you to easily load and display SVG elements in your **TresJS** scene. + +## Usage + +```ts +import { SVG } from '@tresjs/cientos' +``` + +```vue{4} + +``` + +## Props + +| Prop | Type | Description | Default | +| :------------------ | -------------------------------------------------| :------------------------------------------------------------------------ | ----------- | +| **src** | `string` | Either a path to an SVG *or* an SVG string | | +| **skipStrokes** | `boolean` | If `true`, the SVG strokes will not be rendered. | `false` | +| **skipFills** | `boolean` | If `true`, the SVG fills will not be rendered. | `false` | +| **strokeMaterial** | `MeshBasicMaterialParameters` | Props to assign to the stroke materials of the resulting meshes. | `undefined` | +| **fillMaterial** | `MeshBasicMaterialParameters` | Props to assign to the fill materials of the resulting meshes. | `undefined` | +| **strokeMeshProps** | `TresOptions` | Props to assign to the resulting stroke meshes. | `undefined` | +| **fillMeshProps** | `TresOptions` | Props to assign to the resulting fill meshes. | `undefined` | +| **depth** | `'flat' \| 'renderOrder' \| 'offsetZ' \| number` | How should the meshes be "stacked"? ([See "Depth"](#depth)) | `flat` | + +## Depth + +The `SVG` component's `depth` prop allows you to specify how the 2D layers will be rendered in 3D. It accepts the following values: + +### `'flat'` + +**Use case: simple SVGs** + +This is the default `depth` value. This option sets the [materials' `depthWrite`](https://threejs.org/docs/?q=mesh#api/en/materials/Material.depthWrite) to `false`. + +Disadvantage: Overlapping layers in an SVG may be drawn out of order, depending on viewing perspective. + +### `'renderOrder'` + +**Use case: Lone SVGs** + +This value sets the materials' `depthWrite` to `false` and increments the [meshes' `renderOrder`](https://threejs.org/docs/?q=mesh#api/en/core/Object3D.renderOrder) of the mesh layers. This makes the SVG layers render dependably regardless of perspective. + +Disadvantage: SVG layers with higher `renderOrder` will be rendered after (i.e., sometimes "on top of") other objects in the scene graph with a lower `renderOrder`, even if those other objects are closer to the camera. + +### `'zOffset'` + +**Use case: unscaled SVGs seen from the front** + +When this value is passed, the result is a 3D "stack" of mesh layers. A small space is added between each mesh layer in the "stack". + +Disadvantage: When seen from behind, the "bottom" of the "stack" is visible. The space between the layers may be visible depending on viewing perspective. The layers may [z-fight](https://en.wikipedia.org/wiki/Z-fighting), particularly if the SVG is scaled down. + +### `number` + +**Use case: SVGs seen from the front** + +This is the same as `'zOffset'` but allows you to specify how much space is added between each layer, in order to eliminate [z-fighting](https://en.wikipedia.org/wiki/Z-fighting). For most use cases, this should be a value greater than 0.025 and less than 1. + +## Troubleshooting + +::: warning +This is not a general-purpose SVG renderer. Many SVG features are unsupported. +::: + +Here are some things to try if you run into problems: + +### Error: "XML Parsing Error: unclosed token" + +* In the SVG source, convert hex colors to rgb, e.g., convert `#ff0000` to `rgb(255, 0, 0)`. + +### Parts of the SVG render in the wrong order or disappear, depending on viewing angle + +* In the component, [change the `depth` prop](#depth). +* In the SVG source, use `fill="none"` rather than `fill-opacity="0"`. + +### Parts of the SVG ["z-fight"](https://en.wikipedia.org/wiki/Z-fighting) + +* In the component, [change the `depth` prop](#depth). +* Increase the distance between the component and other on-screen elements. \ No newline at end of file