feat!: 986 remove usetexture (#1008)

* feat!: remove useTexture composable and update documentation

BREAKING CHANGE: `useTexture` composable has been refactored and moved to `@tresjs/cientos` package

- Deleted the `useTexture` composable and its associated files as it has been refactored and moved to the `@tresjs/cientos` package.
- Updated documentation to reflect the changes, including a warning about the deprecation and a link to the new `cientos` documentation for `useTexture`.
- Adjusted examples in the cookbook to utilize the new `useTexture` from `@tresjs/cientos`, ensuring users are directed to the correct implementation.

* fix: clean up texture loading examples in documentation

- Removed unnecessary line breaks and improved formatting in the `load-textures.md` documentation.
- Streamlined the example code for `TresMeshStandardMaterial` to enhance readability and maintain consistency with coding standards.

* docs: update composables documentation to reflect removal of useTexture

- Removed deprecated `useTexture` section from the documentation, indicating its refactor to the `@tresjs/cientos` package.
- Added a warning about the deprecation and provided a link to the new `cientos` documentation for user guidance.
- Ensured that the remaining documentation is clear and concise, maintaining consistency with the latest changes in the codebase.

docs/api/composables.md

@@ -262,101 +262,6 @@ import { GLTFLoader } from 'three/addons/loaders/GLTFLoader'
 The `UseLoader` component needs to be wrapped in a `Suspense` component in order to work
 :::
 
-## useTexture
-
-The `useTexture` composable allows you to load textures using the [THREE.js texture loader](https://threejs.org/docs/#api/en/loaders/TextureLoader). It returns a promise with the loaded texture(s).
-
-```ts
-const texture = await useTexture(['path/to/texture.png'])
-```
-
-**useTexture** also accepts an object with the following properties:
-
-- `map`: a basic texture that is applied to the surface of an object
-- `displacementMap`: a texture that is used to add bumps or indentations to the object's surface
-- `normalMap`: a texture that is used to add surface detail to and variations in shading to the object
-- `roughnessMap`: a texture that is used to add roughness or a matte finish to the object's surface
-- `metalnessMap`: a texture that is used to add a metallic effect to the object's surface
-- `aoMap`: a texture that is used to add ambient occlusion (shading in areas where light is blocked by other objects) to the object.
-- `alphaMap`: a texture that is used to add alpha (the black part render as transparent) to the object. It's necessary to set :trasparent="true" on the material to use this map
-- `matcap`: this textures encodes the material color and shading.
-
-In that case it will return an object with the loaded textures.
-
-```ts
-const { map, displacementMap, normalMap, roughnessMap, metalnessMap, aoMap, alphaMap, matcap } = await useTexture({
-  map: 'path/to/albedo.png',
-  displacementMap: 'path/to/height.png',
-  normalMap: 'path/to/normal.png',
-  roughnessMap: 'path/to/roughness.png',
-  metalnessMap: 'path/to/metalness.png',
-  aoMap: 'path/to/ambien-occlusion.png',
-  alphaMap: 'path/to/alpha.png',
-  matcap: 'path/to/matcap.png',
-})
-```
-
-Then you can bind the textures to the material.
-
-```vue
-<template>
-  <TresCanvas>
-    <TresMesh>
-      <TresSphereGeometry />
-      <TresMeshStandardMaterial
-        :map="map"
-        :displacement-map="displacementMap"
-        :normal-map="normalMap"
-        :roughness-map="roughnessMap"
-        :metalness-map="metalnessMap"
-        :ao-map="aoMap"
-        :alpha-map="alphaMap"
-      />
-    </TresMesh>
-  </TresCanvas>
-</template>
-```
-
-`useTexture` by default takes the second argument 'manager' as LoadingManager. When omitted, it will automatically be added to `THREE.DefaultLoadingManager`. Of course, you can also add your own LoadingManager, like this:
-```ts
-const loadingManager = new LoadingManager()
-const texture = await useTexture({ map: 'path/to/texture.png' }, loadingManager)
-```
-
-Similar to above composable, the `useTexture` composable returns a promise, you can use it with `async/await` or `then/catch`. If you are using it on a component make sure you wrap it with a `Suspense` component.
-
-### UseTexture as component
-
-You can also use `UseTexture` (with uppercase) as component like so:
-
-```html
-<Suspense>
-  <UseTexture v-slot="{ textures }" map="path/to/texture.png">
-    <TresMesh>
-      <TresBoxGeometry />
-      <TresMeshStandardMaterial :map="textures.map" />
-    </TresMesh>
-  </UseTexture>
-</Suspense>
-```
-
-### Props
-
-| Prop | type |
-| ---- | --- |
-| **map?** | `String` |
-| **displacementMap?** | `String` |
-| **normalMap?** | `String` |
-| **roughnessMap?** | `String` |
-| **metalnessMap?** | `String` |
-| **aoMap?** | `String` |
-| **alphaMap?** | `String` |
-| **matcap?** | `String` |
-
-::: warning
-The `UseTexture` component needs to be wrapped in a `Suspense` component in order to work
-:::
-
 ## useSeek <Badge text="deprecated" />
 
 ::: danger

docs/cookbook/load-textures.md

@@ -28,9 +28,12 @@ For a detailed explanation of how to use `useLoader`, check out the [useLoader](
 
 ```ts
 import { useLoader } from '@tresjs/core'
-import { TextureLoader } from 'three'
+import { Texture, TextureLoader } from 'three'
 
-const texture = useLoader(TextureLoader, '/Rock035_2K_Color.jpg')
+const { state: texture, isLoading } = useLoader(
+  TextureLoader,
+  '/Rock035_2K_Color.jpg',
+)
 ```
 
 Then you can pass the texture to a material:
@@ -54,12 +57,18 @@ import TexturedSphere from './TexturedSphere.vue'
 </template>
 ```
 
-```vue [Model.vue]
+```vue [TexturedSphere.vue]
 <script setup lang="ts">
 import { useLoader } from '@tresjs/core'
 import { TextureLoader } from 'three'
 
-const texture = useLoader(TextureLoader, '/Rock035_2K_Color.jpg')
+const { state: texture, isLoading } = useLoader(
+  TextureLoader,
+  '/Rock035_2K_Color.jpg',
+  {
+    initialValue: new Texture(),
+  },
+)
 </script>
 
 <template>
@@ -71,37 +80,25 @@ const texture = useLoader(TextureLoader, '/Rock035_2K_Color.jpg')
 ```
 :::
 
-## Using `useTexture`
+::: tip
+To avoid using v-if on the material, you can set a default texture as the initial value of the `state` property.
+:::
 
-A more convenient way of loading textures is using the `useTexture` composable. It accepts both an array of URLs or a single object with the texture paths mapped.
+## Using `useTexture`
 
-To learn more about `useTexture`, check out the [useTexture](/api/composables#use-texture) documentation.
+A more convenient way of loading textures is using the `useTexture` and `useTextures` composables from the `@tresjs/cientos` package.
+To learn more about `useTexture`, check out the [useTexture](https://cientos.tresjs.org/guide/loaders/useTexture) documentation.
 
 ```ts
-import { useTexture } from '@tresjs/core'
-
-const pbrTexture = await useTexture({
-  map: '/textures/black-rock/Rock035_2K_Displacement.jpg',
-  displacementMap: '/textures/black-rock/Rock035_2K_Displacement.jpg',
-  roughnessMap: '/textures/black-rock/Rock035_2K_Roughness.jpg',
-  normalMap: '/textures/black-rock/Rock035_2K_NormalDX.jpg',
-  aoMap: '/textures/black-rock/Rock035_2K_AmbientOcclusion.jpg',
-  metalnessMap: '/textures/black-rock/myMetalnessTexture.jpg',
-  matcap: '/textures/black-rock/myMatcapTexture.jpg',
-  alphaMap: '/textures/black-rock/myAlphaMapTexture.jpg'
-})
+import { useTexture } from '@tresjs/cientos'
+
+const { state: texture, isLoading } = useTexture('/Rock035_2K_Color.jpg')
 ```
 Similar to the previous example, we can pass all the textures to a material via props:
 
 ```html
 <TresMesh>
   <TresSphereGeometry :args="[1,32,32]" />
-  <TresMeshStandardMaterial
-    :map="pbrTexture.map"
-    :displacementMap="pbrTexture.displacementMap"
-    :roughnessMap="pbrTexture.roughnessMap"
-    :normalMap="pbrTexture.normalMap"
-    :aoMap="pbrTexture.ambientOcclusionMap"
-  />
+  <TresMeshStandardMaterial :map="texture" />
 </TresMesh>
 ```

src/composables/index.ts

@@ -1,5 +1,4 @@
 import UseLoader from './useLoader/component.vue'
-import UseTexture from './useTexture/component.vue'
 
 export * from './useCamera/'
 export * from './useGraph'
@@ -8,7 +7,7 @@ export * from './useLoop'
 export * from './useRaycaster'
 export * from './useRenderer/useRendererManager'
 export * from './useRenderLoop'
-export * from './useTexture'
+
 export * from './useTresContextProvider'
 export * from './useTresEventManager'
-export { UseLoader, UseTexture }
+export { UseLoader }

src/composables/useTexture/component.vue

@@ -1,13 +0,0 @@
-<script setup lang="ts">
-import type { PBRUseTextureMap } from './index'
-import { reactive } from 'vue'
-import { useTexture } from './index'
-
-const props = defineProps<PBRUseTextureMap>()
-
-const data = await reactive(useTexture(props))
-</script>
-
-<template>
-  <slot :textures="data"></slot>
-</template>

src/composables/useTexture/index.ts

@@ -1,161 +0,0 @@
-import type { LoadingManager, Texture } from 'three'
-import { TextureLoader } from 'three'
-import { isArray } from '../../utils/is'
-
-export interface PBRMaterialOptions {
-  /**
-   * List of texture maps to load.
-   *
-   * @type {string[]}
-   * @memberof PBRMaterialOptions
-   */
-  maps: string[]
-  /**
-   * Path to the texture maps.
-   *
-   * @type {('png' | 'jpg')}
-   * @memberof PBRMaterialOptions
-   */
-  ext: 'png' | 'jpg'
-}
-
-export interface PBRTextureMaps {
-  [key: string]: Texture | null
-}
-
-/**
- * Map of textures to load that can be passed to `useTexture()`.
- */
-export interface PBRUseTextureMap {
-  map?: string
-  displacementMap?: string
-  normalMap?: string
-  roughnessMap?: string
-  metalnessMap?: string
-  aoMap?: string
-  alphaMap?: string
-  matcap?: string
-}
-
-/**
- * Loads a single texture.
- *
- * ```ts
- * import { useTexture } from 'tres'
- *
- * const matcapTexture = await useTexture(['path/to/texture.png'])
- * ```
- * Then you can use the texture in your material.
- *
- * ```vue
- * <TresMeshMatcapMaterial :matcap="matcapTexture" />
- * ```
- * @see https://tresjs.org/examples/load-textures.html
- * @export
- * @param paths
- * @return A promise of the resulting texture
- */
-export async function useTexture(paths: readonly [string]): Promise<Texture>
-/**
- * Loads multiple textures.
- *
- * ```ts
- * import { useTexture } from 'tres'
- *
- * const [texture1, texture2] = await useTexture([
- *  'path/to/texture1.png',
- *  'path/to/texture2.png',
- * ])
- * ```
- * Then you can use the texture in your material.
- *
- * ```vue
- * <TresMeshStandardMaterial map="texture1" />
- * ```
- * @see https://tresjs.org/examples/load-textures.html
- * @export
- * @param paths
- * @return A promise of the resulting textures
- */
-export async function useTexture<T extends string[]>(
-  paths: [...T]
-): Promise<{ [K in keyof T]: Texture }>
-/**
- * Loads a PBR texture map.
- *
- * ```ts
- * import { useTexture } from 'tres'
- *
- * const pbrTexture = await useTexture({
- *  map: 'path/to/texture.png',
- *  displacementMap: 'path/to/displacement-map.png',
- *  roughnessMap: 'path/to/roughness-map.png',
- *  normalMap: 'path/to/normal-map.png',
- *  ambientOcclusionMap: 'path/to/ambient-occlusion-map.png',
- * })
- * ```
- * Then you can use the texture in your material.
- *
- * ```vue
- * <TresMeshStandardMaterial v-bind="pbrTexture" />
- * ```
- * @see https://tresjs.org/examples/load-textures.html
- * @export
- * @param paths
- * @return A promise of the resulting pbr texture map
- */
-export async function useTexture<TextureMap extends PBRUseTextureMap>(
-  paths: TextureMap
-): Promise<{
-  [K in keyof Required<PBRUseTextureMap>]: K extends keyof TextureMap
-    ? Texture
-    : null
-}>
-
-export async function useTexture(
-  paths: readonly [string] | string[] | PBRUseTextureMap,
-  manager?: LoadingManager,
-): Promise<Texture | Texture[] | PBRTextureMaps> {
-  const textureLoader = new TextureLoader(manager)
-
-  /**
-   * Load a texture.
-   *
-   * @param {string} url
-   * @return {*}  {Promise<Texture>}
-   */
-  const loadTexture = (url: string): Promise<Texture> => new Promise((resolve, reject) => {
-    textureLoader.load(
-      url,
-      texture => resolve(texture),
-      () => null,
-      () => {
-        reject(new Error('[useTextures] - Failed to load texture'))
-      },
-    )
-  })
-
-  if (isArray(paths)) {
-    const textures = await Promise.all((paths as Array<string>).map(path => loadTexture(path)))
-    if ((paths as Array<string>).length > 1) {
-      return textures
-    }
-    else {
-      return textures[0]
-    }
-  }
-  else {
-    const { map, displacementMap, normalMap, roughnessMap, metalnessMap, aoMap, alphaMap, matcap,
-    } = paths as { [key: string]: string }
-    return {
-      map: map ? await loadTexture(map) : null,
-      displacementMap: displacementMap ? await loadTexture(displacementMap) : null,
-      normalMap: normalMap ? await loadTexture(normalMap) : null,
-      roughnessMap: roughnessMap ? await loadTexture(roughnessMap) : null,
-      metalnessMap: metalnessMap ? await loadTexture(metalnessMap) : null,
-      aoMap: aoMap ? await loadTexture(aoMap) : null,
-      alphaMap: alphaMap ? await loadTexture(alphaMap) : null,
-      matcap: matcap ? await loadTexture(matcap) : null,
-    }
-  }
-}

src/composables/useTexture/useTexture.test.ts

@@ -1,19 +0,0 @@
-import { LoadingManager, TextureLoader } from 'three'
-import { useTexture } from '.'
-
-describe('useTexture', () => {
-  afterEach(() => {
-    vi.restoreAllMocks()
-  })
-  // TODO: Add tests, maybe mock the texture loader?
-  it.todo('should load a single texture', async () => {
-    const loadingManager = new LoadingManager()
-    const textureLoader = new TextureLoader(loadingManager)
-
-    const spy = vi.spyOn(textureLoader, 'load').mockImplementation(() => {})
-    await useTexture([
-      'https://github.com/Tresjs/assets/blob/main/textures/stylized-grass/stylized-grass1_albedo.png?raw=true',
-    ])
-    expect(spy).toHaveBeenCalledTimes(1)
-  })
-})