feat(Lines): adjust types

Tresjs · Oct 1, 2023 · e876314 · e876314
1 parent 6ab3ef5
commit e876314
Show file tree

Hide file tree

Showing 6 changed files with 48 additions and 14 deletions.
diff --git a/docs/.vitepress/theme/components/CatmullRomCurve3Demo.vue b/docs/.vitepress/theme/components/CatmullRomCurve3Demo.vue
@@ -1,12 +1,13 @@
 <script setup lang="ts">
+import { Vector3 } from 'three'
 import { TresCanvas } from '@tresjs/core'
 import { CatmullRomCurve3, OrbitControls } from '@tresjs/cientos'
 </script>
 
 <template>
   <TresCanvas v-bind="{ clearColor: '#4f4f4f' }">
     <CatmullRomCurve3
-      :points="[[-1.5, 0, 0], [-0.5, 1, 0], [0.5, 0, 0], [1.5, 1, 0]]"
+      :points="[[-1.5, 0, 0], new Vector3(-0.5, 1, 0), [0.5, 0, 0], [1.5, 1, 0]]"
       :segments="40"
       :line-width="10"
       color="#fbb03b"

diff --git a/docs/.vitepress/theme/components/Line2Demo.vue b/docs/.vitepress/theme/components/Line2Demo.vue
@@ -6,7 +6,7 @@ import { OrbitControls, Line2 } from '@tresjs/cientos'
 <template>
   <TresCanvas v-bind="{ clearColor: '#4f4f4f' }">
     <Line2
-      :points="[[-0.5, 0, 0], [0.5, 0, 0], [0, 0.8660, 0], [-0.5, 0, 0]]"
+      :points="[[-0.5, 0, 0], 0.5, 0, 0, [0, 0.8660, 0], [-0.5, 0, 0]]"
       :line-width="10"
       color="#82dbc5"
     />

diff --git a/docs/guide/shapes/catmullromcurve3.md b/docs/guide/shapes/catmullromcurve3.md
@@ -34,11 +34,20 @@ import { CatmullRomCurve3, OrbitControls } from '@tresjs/cientos'
 
 ## Props
 
-`<CatmullRomCurve3 />` accepts [all of `<Line2 />`'s props and uses the same defaults](line2#props). In addition, it accepts the props below.
-
 | Prop         | Type      | Description                                                                   | Default        |
 | ------------ | --------- | ----------------------------------------------------------------------------- | -------------- |
+| points  | `Array<Vector3 \| [number, number, number]>` | Curve's control points |            |
 | segments     | `number`  | Number of points to insert between each pair of points in props.points        | 20             |
 | closed       | `boolean` | The curve will loop back onto itself when this is true.                       | false          |
 | curveType    | `'centripetal' \| 'chordal' \| 'catmullrom'` | Curve type                                 | 'centripetal'  |
 | tension      | `number`  | Catmullrom's tension, when curveType is 'catmullrom'                          | 0.5            |
+| vertexColors    | `TresColor[]`            | Vertex colors, if using                                                    | null           |
+| color           | `TresColor`              | Color for the line – multiplies vertex colors                              | 'white'        |
+| lineWidth       | `number`                 | Width of the line – in world units with size attenuation, pixels otherwise | 1              |
+| worldUnits      | `boolean`                | Whether the line width is in world units or pixels                         | false          |
+| alphaToCoverage | `boolean`                | Enables alpha to coverage. Can only be used with MSAA-enabled contexts (meaning when the renderer was created with antialias parameter set to true).                                                               | false          |
+| dashed          | `boolean`                | Whether the line is dashed                                                 | false          |
+| dashSize        | `number`                 | Dash size                                                                  | 1              |
+| gapSize         | `number`                 | Gap size in dashed line                                                    | 1              |
+| dashScale       | `number`                 | Scale of the dashes/gaps                                                   | 1              |
+| dashOffset      | `number`                 | Dash offset                                                                | 0              |
diff --git a/docs/guide/shapes/line2.md b/docs/guide/shapes/line2.md
@@ -45,12 +45,37 @@ import { Line2, OrbitControls } from '@tresjs/cientos'
 
 ### Points
 
-The points prop can be any of these types:
+The points prop has the following type:
 
-| Type                         | Interpretation                                                                   |
+`Array<Vector3 | Vector2 | [number, number, number] | [number, number] | number>`
+
+The passed array is converted to `Array<number>` – i.e., a series of x, y, z, x, y, z, x ... vertex coordinates. This is done array entry by array entry, as follows:
+
+| Entry type                   | Interpretation                                                                   |
 | ---------------------------- | -------------------------------------------------------------------------------- |
-| `Vector3[]`                  | Each Vector3 maps to a point's x, y, z.                                          |
-| <nobr>`[number, number, number][]`</nobr> | Each entry maps to [x, y, z].                                          |
-| `Vector2[]`                  | Each Vector2 maps to a point's x and y. z = 0.                                   |
-| `[number, number][]`         | Each entry maps to [x, y, 0].                                                    |
-| `number[]`                   | An array of [x, y, z, x, y, z, x ...] coordinates. Length should be a multiple of 3. Proper length is not checked. |
+| `Vector3`                    | Insert the vector's x, y, z into the result array                                |
+| <nobr>`[number, number, number]`</nobr> | Insert the array values into the result array                         |
+| `Vector2`                    | Insert the vector's x, y, then 0 into the result array                           |
+| `[number, number]`           | Insert the array values, then 0 into the result array                            |
+| `number`                     | Insert the number into the result array                                          |
+
+:::warning
+If you pass "bare" numbers in the points array, ensure that you pass "triplets" – groups of three numbers. Otherwise, you'll corrupt the coordinates that follow.
+
+This:
+
+```vue
+//       ✅     ❌     ✅
+:points=[[1,1], 2, 2, [3,3]]
+// result: (1,1,0) (2,2,3) (3,0,?)
+```
+
+So, make sure that you pass three numbers in a row.
+
+```vue
+//       ✅     ✅        ✅
+:points=[[1,1], 2, 2, 0, [3,3]]
+// result: (1,1,0) (2,2,0) (3,3,0)
+```
+The component, like Three.js, will not keep you from shooting yourself in the foot.
+:::
diff --git a/src/core/shapes/CatmullRomCurve3.vue b/src/core/shapes/CatmullRomCurve3.vue
@@ -1,12 +1,11 @@
 <script setup lang="ts">
 import type { TresColor } from '@tresjs/core'
-import type { Vector2 } from 'three'
 import { CatmullRomCurve3, Vector3 } from 'three'
 import { computed } from 'vue'
 import Line2 from './Line2.vue'
 
 type CurveType = 'centripetal' | 'chordal' | 'catmullrom'
-type Points = Array<Vector3 | Vector2 | [number, number, number] | [number, number] | number>
+type Points = Array<Vector3 | [number, number, number]>
 
 interface CatmullRomCurve3Props {
   segments?: number

diff --git a/src/core/shapes/Line2.vue b/src/core/shapes/Line2.vue
@@ -8,7 +8,7 @@ import { watch, onUnmounted, computed } from 'vue'
 import type { TresColor } from '@tresjs/core'
 import { normalizeColor, useTresContext } from '@tresjs/core'
 
-type Points = Vector3[] | Vector2[] | [number, number, number][] | [number, number][] | number[]
+type Points = (Vector3 | Vector2 | [number, number, number] | [number, number] | number)[]
 type VertexColors = Array<TresColor>
 export interface LineProps {
   points: Points