`MeshSurfacePointsSource`

← prev index next →

Scatters a chosen number of clones across a mesh's surface — the way to strew objects over a shape (trees on terrain, studs on a panel, particles over a form) rather than only onto its vertices.

Declarative element: <sk-mesh-surface-points-source>

Not on the sk.* global — construct via the declarative element or a module import.

Remarks

This is a mesh-driven member of the points-source family (see ShaderFunctionPointsSource): a points-source defines the set of positions at which a sk-cloner places copies of its content, so it lives as a child of a <sk-cloner> and the cloner's other child is the template cloned at each point. Unlike sk-mesh-vertex-points-source, which snaps to existing vertices, this one samples the referenced sk-mesh's triangles area-weighted, so you get an arbitrary point count spread over the whole surface with each sample oriented by the interpolated surface normal. Sampling is deterministic for a given seed, so a scene renders the same every time.

Key attributes. mesh references (by #id) the mesh whose surface is sampled (the referenced element is the geometry source, not something drawn at the samples). sample-count is how many points to place — independent of the mesh's vertex count, so a low-poly shape can host thousands of clones. distribution chooses random (fast, area-weighted) or poisson-disk (keeps a minimum spacing for even, non-clumping coverage); with poisson-disk, min-distance sets that spacing (auto-derived if omitted, and the actual count may fall short of sample-count when space runs out). seed re-rolls the scatter to a different but still reproducible layout.

Related. To place clones exactly on a mesh's vertices instead of across its surface, see sk-mesh-vertex-points-source. For placements from an explicit buffer see sk-buffer-points-source; from the GPU see sk-compute-buffer-points-source and sk-custom-wgsl-points-source; from another cloner see sk-cloner-points-source. For built-in procedural shapes see sk-grid-points-source and sk-sphere-points-source. Its host is always a sk-cloner.

Constructor

constructor(config?: { id?: string; mesh?: AbstractMeshNode; sampleCount?: number; distribution?: SurfaceDistribution; minDistance?: number; seed?: number })

Inherited from: SkenraAnimatable — see those pages for inherited members.

Properties

Config Properties

Property	Type	Default	Description	Declared by
`id`config-only	`string`	—	Optional element id assigned to the constructed instance.	`MeshSurfacePointsSourceConfig`
`mesh`animatableread-only	`AbstractMeshNode`	—	The mesh being sampled.	`MeshSurfacePointsSource`
`sampleCount`	`number`	`1`	Requested number of samples.	`MeshSurfacePointsSource`
`distribution`	`SurfaceDistribution`	`"random"`	Distribution method used for sampling.	`MeshSurfacePointsSource`
`minDistance`	`number`	—	Minimum distance between samples (for Poisson disk distribution).	`MeshSurfacePointsSource`
`seed`	`number`	`0`	Seed for the deterministic pseudo-random sampler.	`MeshSurfacePointsSource`

Other Properties

Property	Type	Default	Description	Declared by
`pointCount`read-only	`number`	—	Number of sampled points.	`MeshSurfacePointsSource`
`localMatrices`read-only	`Float32Array<ArrayBufferLike>`	—	Per-element local matrices materialized from the sampled positions and	`MeshSurfacePointsSource`
`scene`read-only	`any`	—	Gets the Scene this animatable belongs to, if any.	`SkenraAnimatable`
`animations`read-only	`SkenraAnimation[]`	—	Public getter for the animations affecting this target.	`SkenraAnimatable`

Methods

Method	Description	Declared by
`configure(mesh: AbstractMeshNode, config: MeshSurfacePointsSourceConfig): void`	Programmatic configure API.	`MeshSurfacePointsSource`
`getBoundsInSpace(fullTransform: Float32Array): { minX: number; maxX: number; minY: number; maxY: number; minZ: number; maxZ: number; } \| null`	Axis-aligned bounding box of the produced points, expressed in the given target space, or `null` if there is no data yet.	`MeshSurfacePointsSource`
`setWorldReferenceNode(node: WorldReferenceNode \| null): void`	Sets the reference node whose world matrix should be used for transforms.	`MeshSurfacePointsSource`
`animate(firstArg: TypedKeyframe<this>[] \| TypedPropertyIndexedKeyframes<this> \| Record<string, any> \| globalThis.Keyframe[] \| globalThis.PropertyIndexedKeyframes \| null, secondArg?: number \| KeyframeAnimationOptions \| globalThis.KeyframeAnimationOptions): SkenraAnimation & Animation`	Creates a new SkenraAnimation for this target per Web Animations API.	`SkenraAnimatable`
`removeAnimation(animation: SkenraAnimation): boolean`	Removes a specific animation from this object.	`SkenraAnimatable`
`constrain(type: K, config: ConstraintConfigMap[K]): ConstraintReturnMap[K]`	Creates a constraint on this Animatable using a fluent API.	`SkenraAnimatable`

Example

// Sample 5000 points on terrain mesh surface
const terrainSamples = new MeshSurfacePointsSource({
    mesh: terrainMesh,
    sampleCount: 5000,
    distribution: 'random'
});

const forestCloner = new Cloner({ id: 'forest',
    pointsSource: terrainSamples,
    alignToNormal: true // Trees align to terrain surface
});
forestCloner.appendChild(treeNode);

↑ Documentation home · ← All classes