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.
JavaScript API:
MeshSurfacePointsSource
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.
Serve these docs to run the live example.
WebGPU needs a secure context — open this page via grunt serve
rather than double-clicking the file. The Markup tab works from disk.
<!-- 200 small spheres strewn across a bigger sphere's surface — placed anywhere
on its triangles, not snapped to its vertices. The points source references
the host by id, then scatters `sample-count` points over the surface;
`distribution="poisson-disk"` with `min-distance` keeps them evenly spaced
instead of clumping (the default `random` distribution can clump). The host
is hidden — only its surface is sampled. Change the seed to re-roll the
layout, or the sample-count to add clones. -->
<sk-scene>
<sk-plain-material id="mat" base-color="steelblue"></sk-plain-material>
<sk-cloner mode="vertex">
<sk-mesh-surface-points-source mesh="#host" sample-count="200"
distribution="poisson-disk" min-distance="0.4" seed="7"></sk-mesh-surface-points-source>
<!-- Template cloned at each sampled point. -->
<sk-sphere radius="0.18">
<sk-surface-paint material="#mat"></sk-surface-paint>
</sk-sphere>
</sk-cloner>
<!-- The host mesh whose surface is sampled (hidden; only its surface is used). -->
<sk-sphere id="host" radius="3" style="content-visibility: hidden"></sk-sphere>
</sk-scene>| Attribute | Type | Default | Description |
|---|---|---|---|
id |
<id> |
— | The element's unique identifier — the standard HTML global id attribute. |
meshrequiredanimatable |
<id-ref> |
— | Source mesh INSTANCE for the imperative construction path. reference by id |
sample-count |
<number> |
1 |
Number of surface samples to generate. |
distribution |
<mesh-distribution> ("random" | "poisson-disk") |
"random" |
Sampling distribution method. |
min-distance |
<number> |
— | Minimum distance between samples (for Poisson disk distribution). |
seed |
<number> |
0 |
Seed for the deterministic pseudo-random sampler. |