@tresjs/core 1.6.3 → 1.8.0

package/dist/core/index.d.ts

@@ -7,3 +7,4 @@ export * from './useScene/';
 export * from './useLoader';
 export * from './useTexture';
 export * from './useTres';
+export * from './useRaycaster';

package/dist/core/useCamera/index.d.ts

@@ -1,31 +1,96 @@
 import { PerspectiveCamera, OrthographicCamera } from 'three';
-import { ComputedRef } from 'vue';
+import { Ref } from 'vue';
 export declare enum CameraType {
     Perspective = "Perspective",
     Orthographic = "Orthographic"
 }
 export type Camera = PerspectiveCamera | OrthographicCamera;
-export type CameraState = {
-    cameras: Array<Camera>;
-};
 export interface PerspectiveCameraOptions {
+    /**
+     * Camera frustum vertical field of view, from bottom to top of view, in degrees.
+     *
+     * @type {number}
+     * @memberof PerspectiveCameraOptions
+     */
     fov?: number;
+    /**
+     * Camera frustum near plane.
+     *
+     * @type {number}
+     * @memberof PerspectiveCameraOptions
+     */
     near?: number;
+    /**
+     * Camera frustum far plane.
+     *
+     * @type {number}
+     * @memberof PerspectiveCameraOptions
+     */
     far?: number;
 }
 export interface OrthographicCameraOptions {
+    /**
+     * Camera frustum left plane.
+     *
+     * @type {number}
+     * @memberof OrthographicCameraOptions
+     */
     left?: number;
+    /**
+     * Camera frustum right plane.
+     *
+     * @type {number}
+     * @memberof OrthographicCameraOptions
+     */
     right?: number;
+    /**
+     * Camera frustum top plane.
+     *
+     * @type {number}
+     * @memberof OrthographicCameraOptions
+     */
     top?: number;
+    /**
+     * Camera frustum bottom plane.
+     *
+     * @type {number}
+     * @memberof OrthographicCameraOptions
+     */
     bottom?: number;
+    /**
+     * Camera frustum near plane.
+     *
+     * @type {number}
+     * @memberof OrthographicCameraOptions
+     */
     near?: number;
+    /**
+     * Camera frustum far plane.
+     *
+     * @type {number}
+     * @memberof OrthographicCameraOptions
+     */
     far?: number;
 }
 interface UseCameraReturn {
-    activeCamera: ComputedRef<Camera>;
+    activeCamera: Ref<Camera | undefined>;
     createCamera: (cameraType?: CameraType, options?: PerspectiveCameraOptions | OrthographicCameraOptions) => Camera;
     updateCamera: () => void;
     pushCamera: (camera: Camera) => void;
+    clearCameras: () => void;
 }
+/**
+ * Create and update cameras
+ *
+ * ```ts
+ * import { useCamera } from '@tresjs/core'
+ * const { createCamera, updateCamera } = useCamera()
+ * const camera = createCamera(new PerspectiveCamera(45, 1, 0.1, 1000))
+ * updateCamera()
+ * ```
+ *
+ * @export
+ * @return {*}  {UseCameraReturn}
+ */
 export declare function useCamera(): UseCameraReturn;
 export {};

package/dist/core/useCatalogue/index.d.ts

@@ -1,5 +1,19 @@
 import { App, Ref } from 'vue';
 import { TresCatalogue } from '../../types';
+/**
+ * State for the catalogue of THREE objects
+ *
+ * ```ts
+ * const { catalogue } = useCatalogue()
+ *
+ * console.log(catalogue.value.Mesh) // Mesh
+ * ```
+ *
+ * @export
+ * @param {App} [app]
+ * @param {string} [prefix='Tres']
+ * @return {*}
+ */
 export declare function useCatalogue(app?: App, prefix?: string): {
     extend: (objects: any) => void;
     catalogue: Ref<TresCatalogue>;

package/dist/core/useInstanceCreator/index.d.ts

@@ -1,5 +1,12 @@
 import { Ref } from 'vue';
 import { TresCatalogue, TresInstance, TresVNode } from '../../types';
+/**
+ * Composable responsible for creating instances out of Three.js objects.
+ *
+ * @export
+ * @param {string} prefix
+ * @return {*}
+ */
 export declare function useInstanceCreator(prefix: string): {
     createComponentInstances: (catalogue: Ref<TresCatalogue>) => (string | import("vue").DefineComponent<{}, () => void, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").VNodeProps & import("vue").AllowedComponentProps & import("vue").ComponentCustomProps, Readonly<import("vue").ExtractPropTypes<{}>>, {}>)[][];
     processProps: (props: Record<string, any>, instance: TresInstance) => void;

package/dist/core/useLoader/index.d.ts

@@ -1,13 +1,44 @@
 import { Object3D } from 'three';
 export interface TresLoader<T> extends THREE.Loader {
     load(url: string, onLoad?: (result: T) => void, onProgress?: (event: ProgressEvent) => void, onError?: (event: ErrorEvent) => void): unknown;
+    loadAsync(url: string, onProgress?: (event: ProgressEvent) => void): Promise<T>;
 }
 export type LoaderProto<T> = new (...args: any) => TresLoader<T extends unknown ? any : T>;
 export type LoaderReturnType<T, L extends LoaderProto<T>> = T extends unknown ? Awaited<ReturnType<InstanceType<L>['loadAsync']>> : T;
+/**
+ * Traverse an object and return all the nodes and materials
+ *
+ * @export
+ * @param {Object3D} object
+ * @return { [key: string]: any }
+ */
 export declare function trasverseObjects(object: Object3D): {
     [key: string]: any;
 };
 export type Extensions<T extends {
     prototype: LoaderProto<any>;
 }> = (loader: T['prototype']) => void;
+/**
+ * Load resources using THREE loaders and return the result as a promise
+ *
+ * @see https://tresjs.org/api/composables.html#useloader
+ * @see https://threejs.org/docs/index.html?q=loader#api/en/loaders/Loader
+ *
+ * ```ts
+ * import { useLoader } from '@tresjs/core'
+ * import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader'
+ *
+ * const { scene } = await useLoader(THREE.GLTFLoader, 'path/to/asset.gltf')
+ * ```
+ *
+ * @export
+ * @template T
+ * @template U
+ * @param {T} Loader
+ * @param {U} url
+ * @param {Extensions<T>} [extensions]
+ * @param {(event: ProgressEvent<EventTarget>) => void} [onProgress]
+ * @param {(proto: TresLoader<T>) => void} [cb]
+ * @return {*}
+ */
 export declare function useLoader<T extends LoaderProto<T>, U extends string | string[]>(Loader: T, url: U, extensions?: Extensions<T>, onProgress?: (event: ProgressEvent<EventTarget>) => void, cb?: (proto: TresLoader<T>) => void): Promise<U extends any[] ? LoaderReturnType<T, T>[] : LoaderReturnType<T, T>>;

package/dist/core/useRaycaster/index.d.ts

@@ -1,66 +1,32 @@
 import { Raycaster, Vector2 } from 'three';
-export declare function useRaycaster(): {
-    raycaster: import("vue").ShallowRef<Raycaster>;
-    pointer: import("vue").Ref<{
-        x: number;
-        y: number;
-        width: number;
-        height: number;
-        readonly isVector2: true;
-        set: (x: number, y: number) => Vector2;
-        setScalar: (scalar: number) => Vector2;
-        setX: (x: number) => Vector2;
-        setY: (y: number) => Vector2;
-        setComponent: (index: number, value: number) => Vector2;
-        getComponent: (index: number) => number;
-        clone: () => Vector2;
-        copy: (v: Vector2) => Vector2;
-        add: (v: Vector2, w?: Vector2 | undefined) => Vector2;
-        addScalar: (s: number) => Vector2;
-        addVectors: (a: Vector2, b: Vector2) => Vector2;
-        addScaledVector: (v: Vector2, s: number) => Vector2;
-        sub: (v: Vector2) => Vector2;
-        subScalar: (s: number) => Vector2;
-        subVectors: (a: Vector2, b: Vector2) => Vector2;
-        multiply: (v: Vector2) => Vector2;
-        multiplyScalar: (scalar: number) => Vector2;
-        divide: (v: Vector2) => Vector2;
-        divideScalar: (s: number) => Vector2;
-        applyMatrix3: (m: import("three").Matrix3) => Vector2;
-        min: (v: Vector2) => Vector2;
-        max: (v: Vector2) => Vector2;
-        clamp: (min: Vector2, max: Vector2) => Vector2;
-        clampScalar: (min: number, max: number) => Vector2;
-        clampLength: (min: number, max: number) => Vector2;
-        floor: () => Vector2;
-        ceil: () => Vector2;
-        round: () => Vector2;
-        roundToZero: () => Vector2;
-        negate: () => Vector2;
-        dot: (v: Vector2) => number;
-        cross: (v: Vector2) => number;
-        lengthSq: () => number;
-        length: () => number;
-        lengthManhattan: () => number;
-        manhattanLength: () => number;
-        normalize: () => Vector2;
-        angle: () => number;
-        distanceTo: (v: Vector2) => number;
-        distanceToSquared: (v: Vector2) => number;
-        distanceToManhattan: (v: Vector2) => number;
-        manhattanDistanceTo: (v: Vector2) => number;
-        setLength: (length: number) => Vector2;
-        lerp: (v: Vector2, alpha: number) => Vector2;
-        lerpVectors: (v1: Vector2, v2: Vector2, alpha: number) => Vector2;
-        equals: (v: Vector2) => boolean;
-        fromArray: (array: number[] | ArrayLike<number>, offset?: number | undefined) => Vector2;
-        toArray: {
-            (array?: number[] | undefined, offset?: number | undefined): number[];
-            (array?: import("three").Vector2Tuple | undefined, offset?: 0 | undefined): import("three").Vector2Tuple;
-            (array: ArrayLike<number>, offset?: number | undefined): ArrayLike<number>;
-        };
-        fromBufferAttribute: (attribute: import("three").BufferAttribute, index: number) => Vector2;
-        rotateAround: (center: Vector2, angle: number) => Vector2;
-        random: () => Vector2;
-    }>;
-};
+import { Ref, ShallowRef } from 'vue';
+/**
+ * Raycaster composable return type
+ *
+ * @export
+ * @interface UseRaycasterReturn
+ */
+export interface UseRaycasterReturn {
+    /**
+     * Raycaster instance
+     *
+     * @type {ShallowRef<Raycaster>}
+     * @memberof UseRaycasterReturn
+     */
+    raycaster: ShallowRef<Raycaster>;
+    /**
+     * Pointer position
+     *
+     * @type {Ref<Vector2>}
+     * @memberof UseRaycasterReturn
+     */
+    pointer: Ref<Vector2>;
+}
+/**
+ * Composable to provide raycaster support and pointer information
+ *
+ * @see https://threejs.org/docs/index.html?q=raycas#api/en/core/Raycaster
+ * @export
+ * @return {*} {UseRaycasterReturn}
+ */
+export declare function useRaycaster(): UseRaycasterReturn;

package/dist/core/useRenderer/component.d.ts

@@ -1,12 +1,14 @@
 import { ShadowMapType, TextureEncoding, ToneMapping } from 'three';
 import { PropType } from 'vue';
-/**
- * Vue component for rendering a Tres component.
- */
 export declare const TresCanvas: import("vue").DefineComponent<{
     shadows: BooleanConstructor;
     shadowMapType: PropType<ShadowMapType>;
-    physicallyCorrectLights: BooleanConstructor;
+    physicallyCorrectLights: {
+        type: BooleanConstructor;
+        default: boolean;
+        validator: (value: boolean) => boolean;
+    };
+    useLegacyLights: BooleanConstructor;
     outputEncoding: PropType<TextureEncoding>;
     toneMapping: PropType<ToneMapping>;
     toneMappingExposure: NumberConstructor;
@@ -18,12 +20,18 @@ export declare const TresCanvas: import("vue").DefineComponent<{
         type: BooleanConstructor;
         default: boolean;
     };
+    preset: PropType<"realistic">;
 }, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
     [key: string]: any;
 }> | undefined, unknown, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").VNodeProps & import("vue").AllowedComponentProps & import("vue").ComponentCustomProps, Readonly<import("vue").ExtractPropTypes<{
     shadows: BooleanConstructor;
     shadowMapType: PropType<ShadowMapType>;
-    physicallyCorrectLights: BooleanConstructor;
+    physicallyCorrectLights: {
+        type: BooleanConstructor;
+        default: boolean;
+        validator: (value: boolean) => boolean;
+    };
+    useLegacyLights: BooleanConstructor;
     outputEncoding: PropType<TextureEncoding>;
     toneMapping: PropType<ToneMapping>;
     toneMappingExposure: NumberConstructor;
@@ -35,9 +43,11 @@ export declare const TresCanvas: import("vue").DefineComponent<{
         type: BooleanConstructor;
         default: boolean;
     };
+    preset: PropType<"realistic">;
 }>>, {
     shadows: boolean;
     physicallyCorrectLights: boolean;
+    useLegacyLights: boolean;
     preserveDrawingBuffer: boolean;
     windowSize: boolean;
 }>;

package/dist/core/useRenderer/const.d.ts

@@ -0,0 +1,12 @@
+export declare const rendererPresets: {
+    realistic: {
+        outputEncoding: import("three").TextureEncoding;
+        toneMapping: import("three").ToneMapping;
+        toneMappingExposure: number;
+        shadowMap: {
+            enabled: boolean;
+            type: import("three").ShadowMapType;
+        };
+    };
+};
+export type RendererPresetsType = keyof typeof rendererPresets;

package/dist/core/useRenderer/index.d.ts

@@ -2,6 +2,7 @@ import { MaybeComputedRef, MaybeElementRef } from '@vueuse/core';
 import { WebGLRendererParameters, WebGLRenderer, ShadowMapType } from 'three';
 import type { TextureEncoding, ToneMapping } from 'three';
 import { TresColor } from '../../types';
+import { RendererPresetsType } from './const';
 export interface UseRendererOptions extends WebGLRendererParameters {
     /**
      * Enable shadows in the Renderer
@@ -22,8 +23,16 @@ export interface UseRendererOptions extends WebGLRendererParameters {
      * See the [lights / physical example](https://threejs.org/examples/#webgl_lights_physical).
      *
      * @default false
+     * @deprecated Use {@link WebGLRenderer.useLegacyLights useLegacyLights} instead.
      */
     physicallyCorrectLights?: MaybeComputedRef<boolean>;
+    /**
+     * Whether to use legacy lighting mode.
+     *
+     * @type {MaybeComputedRef<boolean>}
+     * @memberof UseRendererOptions
+     */
+    useLegacyLights?: MaybeComputedRef<boolean>;
     /**
      * Defines the output encoding of the renderer.
      * Can be LinearEncoding, sRGBEncoding
@@ -70,12 +79,14 @@ export interface UseRendererOptions extends WebGLRendererParameters {
      */
     clearColor?: MaybeComputedRef<TresColor>;
     windowSize?: MaybeComputedRef<boolean>;
+    preset?: RendererPresetsType;
 }
 /**
  * Reactive Three.js WebGLRenderer instance
  *
  * @param canvas
- * @param options
+ * @param container
+ * @param {UseRendererOptions} [options]
  */
 export declare function useRenderer(canvas: MaybeElementRef, container: MaybeElementRef, options: UseRendererOptions): {
     renderer: import("vue").ShallowRef<WebGLRenderer | undefined>;

package/dist/core/useScene/index.d.ts

@@ -1,4 +1,10 @@
 import { Scene } from 'three';
+/**
+ * Composable for accessing the scene.
+ *
+ * @export
+ * @return {*} {ShallowRef<Scene>}
+ */
 export declare function useScene(): {
     scene: import("vue").ShallowRef<Scene>;
 };

package/dist/core/useTexture/index.d.ts

@@ -1,11 +1,49 @@
 import { Texture } from 'three';
 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;
 }
+/**
+ * Composable for loading textures.
+ *
+ * @see https://tresjs.org/examples/load-textures.html
+ *
+ * ```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" />
+ * ```
+ *
+ * @export
+ * @param {(Array<string> | { [key: string]: string })} paths
+ * @return {*}  {(Promise<Texture | Array<Texture> | PBRTextureMaps>)}
+ */
 export declare function useTexture(paths: Array<string> | {
     [key: string]: string;
 }): Promise<Texture | Array<Texture> | PBRTextureMaps>;

package/dist/core/useTres/index.d.ts

@@ -1,14 +1,116 @@
-import { WebGLRenderer } from 'three';
+import { Clock, EventDispatcher, Raycaster, Scene, Vector2, WebGLRenderer } from 'three';
+import { ComputedRef } from 'vue';
 import { Camera } from '../../core';
 export interface TresState {
+    /**
+     * The active camera used for rendering the scene.
+     *
+     * @see https://threejs.org/docs/index.html?q=camera#api/en/cameras/Camera
+     *
+     * @type {Camera}
+     * @memberof TresState
+     */
     camera?: Camera;
+    /**
+     * All cameras available in the scene.
+     *
+     * @see https://threejs.org/docs/index.html?q=camera#api/en/cameras/Camera
+     *
+     * @type {Camera[]}
+     * @memberof TresState
+     */
+    cameras?: Camera[];
+    /**
+     * The aspect ratio of the scene.
+     *
+     * @type {ComputedRef<number>}
+     * @memberof TresState
+     */
+    aspectRatio?: ComputedRef<number>;
+    /**
+     * The WebGLRenderer used to display the scene using WebGL.
+     *
+     * @see https://threejs.org/docs/index.html?q=webglren#api/en/renderers/WebGLRenderer
+     *
+     * @type {WebGLRenderer}
+     * @memberof TresState
+     */
     renderer?: WebGLRenderer;
+    /**
+     * The scene. This is the place where you place objects, lights and cameras.
+     *
+     * @see https://threejs.org/docs/index.html?q=scene#api/en/scenes/Scene
+     *
+     * @type {Scene}
+     * @memberof TresState
+     */
+    scene?: Scene;
+    /**
+     * The raycaster.
+     *
+     * @see https://threejs.org/docs/index.html?q=raycas#api/en/core/Raycaster
+     *
+     * @type {Raycaster}
+     * @memberof TresState
+     */
+    raycaster?: Raycaster;
+    /**
+     * Object for keeping track of time. This uses `performance.now` if it is available,
+     * otherwise it reverts to the less accurate `Date.now`.
+     *
+     * @see https://threejs.org/docs/index.html?q=clock#api/en/core/Clock
+     *
+     * @type {Clock}
+     * @memberof TresState
+     */
+    clock?: Clock;
+    /**
+     * The current mouse position.
+     *
+     * @type {Vector2}
+     * @memberof TresState
+     */
+    pointer?: Vector2;
+    /**
+     * The current instance of the component.
+     *
+     * @type {*}
+     * @memberof TresState
+     */
+    currentInstance?: any;
+    /**
+     *  The current active scene control
+     *
+     * @type {((EventDispatcher & { enabled: boolean }) | null)}
+     * @memberof TresState
+     */
+    controls?: (EventDispatcher & {
+        enabled: boolean;
+    }) | null;
     [key: string]: any;
 }
+/**
+ * The Tres state.
+ *
+ * @see https://threejs.org/docs/index.html?q=scene#api/en/scenes/Scene
+ *
+ * @export
+ * @return {*} {TresState, getState, setState}
+ */
 export declare function useTres(): {
     getState: (key: string) => any;
     setState: (key: string, value: any) => void;
     camera?: import("vue").Ref<Camera | undefined> | undefined;
+    cameras?: import("vue").Ref<Camera[] | undefined> | undefined;
+    aspectRatio?: import("vue").Ref<ComputedRef<number> | undefined> | undefined;
     renderer?: import("vue").Ref<WebGLRenderer | undefined> | undefined;
+    scene?: import("vue").Ref<Scene | undefined> | undefined;
+    raycaster?: import("vue").Ref<Raycaster | undefined> | undefined;
+    clock?: import("vue").Ref<Clock | undefined> | undefined;
+    pointer?: import("vue").Ref<Vector2 | undefined> | undefined;
+    currentInstance?: import("vue").Ref<any> | undefined;
+    controls?: import("vue").Ref<(EventDispatcher<import("three").Event> & {
+        enabled: boolean;
+    }) | null | undefined> | undefined;
     state: TresState;
 };

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { App } from 'vue';
 export * from './core';
 export * from './keys';
+export * from './types';
 export interface TresOptions {
     prefix?: string;
     extends?: Record<string, unknown>;