@needle-tools/engine
Version:
Needle Engine is a web-based runtime for 3D apps. It runs on your machine for development with great integrations into editors like Unity or Blender - and can be deployed onto any device! It is flexible, extensible and networking and XR are built-in.
198 lines (197 loc) • 7.75 kB
TypeScript
import { Material, Mesh, MeshPhysicalMaterial, MeshStandardMaterial, Object3D, RawShaderMaterial, ShaderMaterial, SkinnedMesh, Texture, Vector4 } from "three";
import type { IRenderer, ISharedMaterials } from "../engine/engine_types.js";
import { Behaviour } from "./Component.js";
import { InstanceHandle } from "./RendererInstancing.js";
export { InstancingUtil } from "../engine/engine_instancing.js";
export declare enum ReflectionProbeUsage {
Off = 0,
BlendProbes = 1,
BlendProbesAndSkybox = 2,
Simple = 3
}
export declare class FieldWithDefault {
path: string | null;
asset: object | null;
default: any;
}
export declare enum RenderState {
Both = 0,
Back = 1,
Front = 2
}
type SharedMaterial = (Material & Partial<MeshStandardMaterial> & Partial<MeshPhysicalMaterial> & Partial<ShaderMaterial> & Partial<RawShaderMaterial>);
declare class SharedMaterialArray implements ISharedMaterials {
[num: number]: Material;
private _renderer;
private _targets;
private _indexMapMaxIndex?;
private _indexMap?;
private _changed;
get changed(): boolean;
set changed(value: boolean);
is(renderer: Renderer): boolean;
constructor(renderer: Renderer, originalMaterials: Material[]);
get length(): number;
[Symbol.iterator](): Generator<SharedMaterial | null, void, unknown>;
private resolveIndex;
private setMaterial;
private getMaterial;
}
/**
* The [Renderer](https://engine.needle.tools/docs/api/Renderer) component controls rendering properties of meshes including materials,
* lightmaps, reflection probes, and GPU instancing.
*
* **Materials:**
* Access materials via `sharedMaterials` array. Changes affect all instances.
* Use material cloning for per-instance variations.
*
* **Instancing:**
* Enable GPU instancing for improved performance with many identical objects.
* Use `Renderer.setInstanced(obj, true)` or `enableInstancing` property.
*
* **Lightmaps:**
* Baked lighting is automatically applied when exported from Unity or Blender.
* Access via the associated {@link RendererLightmap} component.
*
* [](https://engine.needle.tools/samples/multiple-lightmaps/)
*
* **Debug options:**
* - `?debugrenderer` - Log renderer info
* - `?wireframe` - Show wireframe rendering
* - `?noinstancing` - Disable GPU instancing
*
* @example Change material at runtime
* ```ts
* const renderer = myObject.getComponent(Renderer);
* renderer.sharedMaterials[0] = newMaterial;
* ```
*
* @example Enable instancing
* ```ts
* Renderer.setInstanced(myObject, true);
* ```
*
* @category Rendering
* @group Components
* @see {@link ReflectionProbe} for environment reflections
* @see {@link Light} for scene lighting
*/
export declare class Renderer extends Behaviour implements IRenderer {
/** Enable or disable instancing for an object. This will create a Renderer component if it does not exist yet.
* @returns the Renderer component that was created or already existed on the object
*/
static setInstanced(obj: Object3D, enableInstancing: boolean): Renderer;
/** Check if an object is currently rendered using instancing
* @returns true if the object is rendered using instancing
*/
static isInstanced(obj: Object3D): boolean;
/** Set the rendering state only of an object (makes it visible or invisible) without affecting component state or child hierarchy visibility! You can also just enable/disable the Renderer component on that object for the same effect!
*
* If you want to activate or deactivate a complete object you can use obj.visible as usual (it acts the same as setActive in Unity) */
static setVisible(obj: Object3D, visible: boolean): void;
receiveShadows: boolean;
shadowCastingMode: ShadowCastingMode;
lightmapIndex: number;
lightmapScaleOffset: Vector4;
/** If the renderer should use instancing
* If this is a boolean (true) all materials will be instanced or (false) none of them.
* If this is an array of booleans the materials will be instanced based on the index of the material.
*/
enableInstancing: boolean | boolean[] | undefined;
renderOrder: number[] | undefined;
allowOcclusionWhenDynamic: boolean;
probeAnchor?: Object3D;
reflectionProbeUsage: ReflectionProbeUsage;
private _lightmaps?;
/** Get the mesh Object3D for this renderer
* Warn: if this is a multimaterial object it will return the first mesh only
* @returns a mesh object3D.
* */
get sharedMesh(): Mesh | SkinnedMesh | undefined;
private readonly _sharedMeshes;
/** Get all the mesh Object3D for this renderer
* @returns an array of mesh object3D.
*/
get sharedMeshes(): Mesh[];
get sharedMaterial(): SharedMaterial;
set sharedMaterial(mat: SharedMaterial);
/**@deprecated Use sharedMaterial */
get material(): SharedMaterial;
/**@deprecated Use sharedMaterial */
set material(mat: SharedMaterial);
private _sharedMaterials;
private _originalMaterials?;
private _probeAnchorLastFrame?;
private set sharedMaterials(value);
get sharedMaterials(): SharedMaterialArray;
static get shouldSuppressInstancing(): string | number | boolean;
private _lightmapTextureOverride;
get lightmap(): Texture | null;
/** set undefined to return to default lightmap */
set lightmap(tex: Texture | null | undefined);
get hasLightmap(): boolean;
allowProgressiveLoading: boolean;
private _firstFrame;
registering(): void;
awake(): void;
private applyLightmapping;
private _isInstancingEnabled;
private _handles;
/**
* @returns true if this renderer has instanced objects
*/
get isInstancingActive(): boolean;
/** @returns the instancing handles */
get instances(): InstanceHandle[] | null;
private _handlesTempArray;
/** Enable or disable instancing for this renderer.
* @param enabled true to enable instancing, false to disable it
*/
setInstancingEnabled(enabled: boolean): boolean;
private clearInstancingState;
/** Return true to wrap matrix update events for instanced rendering to update instance matrices automatically when matrixWorld changes
* This is a separate method to be overrideable from user code
*/
useInstanceMatrixWorldAutoUpdate(): boolean;
start(): void;
onEnable(): void;
onDisable(): void;
onDestroy(): void;
private readonly onReflectionProbeEnabled;
private onReflectionProbeDisabled;
onBeforeRender(): void;
private onBeforeRenderThree;
onAfterRender(): void;
/** Applies stencil settings for this renderer's objects (if stencil settings are available) */
applyStencil(): void;
/** Apply the settings of this renderer to the given object
* Settings include shadow casting and receiving (e.g. this.receiveShadows, this.shadowCastingMode)
*/
applySettings(go: Object3D): void;
private _reflectionProbe;
private updateReflectionProbe;
private _updateReflectionProbe;
private setVisibility;
private isMultiMaterialObject;
private isMeshOrSkinnedMesh;
}
export declare class MeshRenderer extends Renderer {
}
/**
* Renders deformable meshes that deform via bones and/or blend shapes.
* @summary Renderer for deformable meshes
* @category Rendering
* @group Components
**/
export declare class SkinnedMeshRenderer extends MeshRenderer {
private _needUpdateBoundingSphere;
awake(): void;
onAfterRender(): void;
markBoundsDirty(): void;
}
export declare enum ShadowCastingMode {
Off = 0,
On = 1,
TwoSided = 2,
ShadowsOnly = 3
}