Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: decal (WIP) #577

Open
wants to merge 36 commits into
base: main
Choose a base branch
from
Open
Changes from 1 commit
Commits
Show all changes
36 commits
Select commit Hold shift + click to select a range
2814365
feat(cientos): Add first version Decal component
damienmontastier Mar 7, 2024
66e4403
Merge branch 'Tresjs:main' into feature/282-add-decal-component
damienmontastier Mar 7, 2024
5154631
feat(cientos): Add first version Decal component console.log
damienmontastier Mar 7, 2024
224d9df
feat(cientos/decal): pre-alpha with corrections
damienmontastier Mar 10, 2024
f7865fd
feat(cientos/decal): add logos, datas json, reorder
damienmontastier Mar 10, 2024
34fa040
feat(cientos/decal): clean up
damienmontastier Mar 11, 2024
672ba67
feat(cientos/decal): clean up v2
damienmontastier Mar 11, 2024
1c67ff5
feat(cientos/decal): clean up, start writing documenation
damienmontastier Mar 12, 2024
690894c
feat(cientos/decal): writing documenation and examples
damienmontastier Mar 12, 2024
64c5a45
feat(cientos/decal): little test
damienmontastier Mar 12, 2024
5f74e76
update
damienmontastier Dec 14, 2024
6ac2810
wip decal debug
damienmontastier Dec 18, 2024
075c61e
wip debug
damienmontastier Dec 18, 2024
0bc13f8
wip debug
damienmontastier Dec 19, 2024
930ca96
wip debug
damienmontastier Dec 21, 2024
2b16a10
wip debug
damienmontastier Dec 21, 2024
aef6f45
wip debug
damienmontastier Dec 21, 2024
ae9ac2a
first version
damienmontastier Dec 21, 2024
8322071
first version
damienmontastier Dec 21, 2024
3ef9aeb
lint index decal
damienmontastier Dec 21, 2024
29d29d5
importDecals from export
damienmontastier Dec 21, 2024
c763288
importDecals from export
damienmontastier Dec 21, 2024
e39b300
fix some issue, add utils file
damienmontastier Dec 21, 2024
0760662
wip ts
damienmontastier Dec 30, 2024
6af05f3
Merge branch 'main' into feature/282-add-decal-component
damienmontastier Dec 30, 2024
cdce104
wip lint fix
damienmontastier Dec 30, 2024
70aee8b
fix eslint and array decals
damienmontastier Dec 30, 2024
8001924
fix eslint and array decals
damienmontastier Dec 30, 2024
cd0f160
fix eslint/ts
damienmontastier Jan 2, 2025
1b7eda9
Merge branch 'main' into feature/282-add-decal-component
damienmontastier Jan 2, 2025
67b6f40
fix eslint/ts
damienmontastier Jan 2, 2025
e573eec
fix eslint/ts
damienmontastier Jan 2, 2025
33aee9c
wip documentation
damienmontastier Jan 3, 2025
b85391e
merge
damienmontastier Jan 24, 2025
5db0c4b
merge main
damienmontastier Feb 13, 2025
260ba1b
add resizer component for debug, test with html abstraction
damienmontastier Feb 17, 2025
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
feat(cientos/decal): clean up, start writing documenation
damienmontastier committed Mar 12, 2024
commit 1c67ff54c74cbf6a38e5210e3ae3bd543cfa212d
1 change: 1 addition & 0 deletions docs/.vitepress/config.ts
Original file line number Diff line number Diff line change
@@ -65,6 +65,7 @@ export default defineConfig({
{ text: 'useFBO', link: '/guide/abstractions/use-fbo' },
{ text: 'useSurfaceSampler', link: '/guide/abstractions/use-surface-sampler' },
{ text: 'Sampler', link: '/guide/abstractions/sampler' },
{ text: 'Decal', link: '/guide/abstractions/decal' },
],
},
{
46 changes: 46 additions & 0 deletions docs/.vitepress/theme/assets/decal/basicDatas.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
{
"three": {
"position": [
1.5363168804445717,
0.8187995145707163,
0.0078670324629595
],
"orientation": [
-1.38857623306136,
1.072949621353386,
1.3640708211183215
],
"size": [
2.25,
2.25,
2.25
],
"normal": [
0.8786128709632215,
0.46962857716986595,
0.08653567173814952
]
},
"vue": {
"position": [
-1.157967479791258,
-0.21184063027023203,
1.2757945122548344
],
"orientation": [
0.12612618734468,
-0.6833155391591204,
0.07988657730313918
],
"size": [
2,
2,
2
],
"normal": [
-0.6313676359983956,
-0.09754968296024379,
0.7693237079202443
]
}
}
16 changes: 16 additions & 0 deletions docs/.vitepress/theme/components/DecalDemo.vue
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
<script setup lang="ts">
import { TresCanvas } from '@tresjs/core'
import { useGLTF, OrbitControls } from '@tresjs/cientos'

</script>

<template>
<TresCanvas clear-color="#82DBC5">
<TresPerspectiveCamera :position="[3, 3, 3]" />
<OrbitControls make-default />

<TresAmbientLight />
<TresDirectionalLight :position="[0, 2, 4]" />
<TresGridHelper />
</TresCanvas>
</template>
20 changes: 20 additions & 0 deletions docs/.vitepress/theme/components/DecalDemoBasic.vue
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
<script setup lang="ts">
import { TresCanvas, useTexture } from '@tresjs/core'
import { Decal, OrbitControls, Sphere } from '@tresjs/cientos'
import decalsDatas from '../assets/decal/basicDatas.json'

const vueLogo = await useTexture(['/cientos/decal/vuejs-logo.png'])
const threejsLogo = await useTexture(['/cientos/decal/threejs-logo.png'])
</script>

<template>
<TresCanvas clearColor="#82DBC5">
<TresPerspectiveCamera :position="[5, 2.5, 5]" />
<OrbitControls make-default auto-rotate />

<Sphere :args="[1.75, 32, 16]">
<Decal v-bind="decalsDatas.three" :map="threejsLogo" />
<Decal v-bind="decalsDatas.vue" :map="vueLogo" />
</Sphere>
</TresCanvas>
</template>
30 changes: 30 additions & 0 deletions docs/.vitepress/theme/components/DecalDemoMaterial.vue
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
<script setup lang="ts">
import { TresCanvas, useTexture } from '@tresjs/core'
import { Decal, OrbitControls, Sphere } from '@tresjs/cientos'
import decalsDatas from '../assets/decal/basicDatas.json'

const vueLogo = await useTexture(['/cientos/decal/vuejs-logo.png'])
const threejsLogo = await useTexture(['/cientos/decal/threejs-logo.png'])
</script>

<template>
<TresCanvas clearColor="#82DBC5">
<TresPerspectiveCamera :position="[5, 2.5, 5]" />
<OrbitControls make-default auto-rotate />

<Sphere :args="[1.75, 32, 16]">
<TresMeshPhysicalMaterial :roughness=".5" color="white" />

<Decal v-bind="decalsDatas.three" :map="threejsLogo">
<TresMeshPhysicalMaterial :roughness=".2" />
</Decal>
<Decal v-bind="decalsDatas.vue" :map="vueLogo">
<TresMeshPhysicalMaterial :roughness=".2" />
</Decal>
</Sphere>

<TresAmbientLight :intensity="1.25" />
<TresDirectionalLight :intensity="1.5" :position="[-2, -1.5, 2]" />
<TresDirectionalLight :intensity="1.5" :position="[2, 1.5, 2]" />
</TresCanvas>
</template>
25 changes: 25 additions & 0 deletions docs/.vitepress/theme/components/DecalDemoMeshProp.vue
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
<script setup lang="ts">
import { shallowRef } from 'vue'
import { TresCanvas, useTexture } from '@tresjs/core'
import { Decal, OrbitControls, Sphere } from '@tresjs/cientos'
import decalsDatas from '../assets/decal/basicDatas.json'

const sphereRef = shallowRef(null);

const vueLogo = await useTexture(['/cientos/decal/vuejs-logo.png'])
const threejsLogo = await useTexture(['/cientos/decal/threejs-logo.png'])
</script>

<template>
<TresCanvas clearColor="#82DBC5">
<TresPerspectiveCamera :position="[5, 2.5, 5]" />
<OrbitControls make-default auto-rotate />

<TresMesh ref="sphereRef">
<TresSphereGeometry :args="[1.75, 32, 16]" />
</TresMesh>

<Decal v-bind="decalsDatas.three" :mesh="sphereRef" :map="threejsLogo" />
<Decal v-bind="decalsDatas.vue" :mesh="sphereRef" :map="vueLogo" />
</TresCanvas>
</template>
127 changes: 127 additions & 0 deletions docs/guide/abstractions/decal.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,127 @@
# Decal

<DocsDemo>
<DecalDemo />
</DocsDemo>

The `cientos` package provides an abstraction of the [Decal Geometry](https://threejs.org/docs/#examples/en/geometries/DecalGeometry), `<Decal>` is versatile, such as enhancing models with unique details, dynamically altering visual environments, or seamlessly covering seams. This geometry generates a decal mesh that seamlessly integrates into your scene.

Thanks to its debugging tool 🛠️, it's much easier to position and orientate Decals on objects, models and so on. It also offers a simple way of exporting the data from your `<Decal>` so you can see it permanently on an element.

::: info
This component is still under development, so please report any problems or suggestions on the [@tresjs/cientos](https://github.com/Tresjs/cientos) repository on GitHub.
:::

## Usage

::: info
In most cases where the `<Decal>` component is used, it is best to use `v-bind` and insert an array object containing data of the `[positions, orientations, sizes, normals]` of a Decal (this data can be recovered using the [debug mode](#debug-mode)).
:::

::: warning
If you modify the position of a parent of `Decal(s)` after having already exported their position(s), you will have to re-export the data with the new positions via [debug mode](#debug-mode).
:::

### Minimal

The minimal version is very easy to set up: you just need to insert a `<Decal>` component with a map props for the Texture and a call to `v-bind`.

*The default material is [MeshBasicMaterial](https://threejs.org/docs/#api/en/materials/MeshBasicMaterial)*.

<DocsDemo>
<DecalDemoBasic />
</DocsDemo>

<<< @/.vitepress/theme/components/DecalDemoBasic.vue{3-4,6-7,16-17}

See [datas](#datas) part to see the contents of the Decal's datas object.

### Various materials
If the [MeshBasicMaterial](https://threejs.org/docs/#api/en/materials/MeshBasicMaterial) doesn't suit you, you can assign the material you want to the `<Decal>`. You can now make them react to light 💡, simply by choosing the material that allows it, in this case the [MeshPhysicalMaterial](https://threejs.org/docs/#api/en/materials/MeshPhysicalMaterial).

<DocsDemo>
<DecalDemoMaterial />
</DocsDemo>

<<< @/.vitepress/theme/components/DecalDemoMaterial.vue{3-4,6-7,18-23}

See [datas](#datas) part to see the contents of the Decal's datas object.

### Mesh Prop
Define the surface to which the decal must attach using the mesh prop.

::: warning
Shapes from [@tresjs/cientos](https://github.com/Tresjs/cientos) repository such as `<Sphere>`, `<Box>`, etc. do not work at the moment. You need to go through the method of using a `<TresMesh />` containing a `<TresGeometry />`.
:::

<DocsDemo>
<DecalDemoMeshProp />
</DocsDemo>

<<< @/.vitepress/theme/components/DecalDemoMeshProp.vue{2,4-5,7,9-10,18,22-23}

See [datas](#datas) part to see the contents of the Decal's datas object.

### With GLB Model
Description

Demo

Code
### Debug Mode
Description

::: warning
Debug mode work obligatory with Orbit Control (Si vous l'avez pas déjà ajouté, faite le)
:::

::: warning
Seulement un debug peut être ajouté par mesh (Voir example en dessous)
:::

::: warning
Partie ou on explique la structure d'un objet exporté par le debug mode
:::

Demo

Code
### V-For
Description

Demo

Code
### SurfaceSampler Example
Description

Demo

Code

## Datas

JSON object for examples : [Minimal](#minimal), [Various materials](#various-materials), [Mesh prop](#mesh-prop)
:::details decalsDatas
<<< @/.vitepress/theme/assets/decal/basicDatas.json
:::

## Props




| Prop | Description | Default |
| :---------------- | :--------------------------------------------------- | ------------------------- |
| **debug** | `boolean` — Debug mode (Useful for positioning Decal) | `false` |
| **map** | [`Texture`](https://threejs.org/docs/#api/en/textures/Texture) or `null` — The color map. The map should be applied to the `<Decal>` when no material is applied as a child. (See [usages](#usage) for more details) | `null` |
| **mesh** | [`Mesh`](https://threejs.org/docs/#api/en/objects/Mesh) or `null` — Define the surface to which the decal must attach using the mesh prop. (See [Mesh Prop](#mesh-prop) part for more details) | `null` |
| **position** | `number[]` — Position of the decal. Transformed into [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3) | `[-9999,-9999,-9999]` |
| **orientation** | `number[]` — Orientation of the decal. Transformed into [`Euler`](https://threejs.org/docs/#api/en/math/Euler) | `[0,0,0]` |
| **size** | `number[]` — Size of the decal. Transformed into [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3) | `[1,1,1]` |
| **normal** | `number[]` — Normal of the decal. Transformed into [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3) | `[0,0,0]` |
| **polygonOffsetFactor** | `number` — Sets the polygon offset factor | `-10` |
| **depthTest** | `boolean` — Whether to have depth test enabled when rendering this material. | `true` |
| **depthWrite** | `boolean` — Whether rendering this material has any effect on the depth buffer. | `false` |
| **order** | `number` — This value allows the default rendering order of scene graph objects to be overridden although opaque and transparent objects remain sorted independently. <br /> **Sorting is from lowest to highest.** | `Math.round(Math.random() * 100)` |

Binary file added docs/public/cientos/decal/LeePerrySmith.glb
Binary file not shown.
Loading